Richard A. Johnson

Ahh, my favorite time of the release, Documentation String Freeze. With every release, us Kubuntu folks seem to struggle a bit, but this time, we have done pretty damn good. We did a complete rewrite of our documentation, getting rid of the old KDE3 documentation. And after doing that, I am just extending the freeze on Kubuntu documentation almost 24 hours. This is going to give us time to have the documentation gone through by Carl, our amazing editor-in-chief who has done a kick ass job.

I am really impressed with the results of this release cycle and the people who helped make the Kubuntu documentation at least a bit better if not a whole lot better. My documentation ninjas include:

• Vikram Dhillon (dhillonv) – forget ninja, this guy is a kamikaze. He pumped out a ton of docs this cycle.
• David Wonderly (DarkwingDuck) – the darkwing duck of a ninja, he pummeled out the Netbook Remix documentation, the Desktop documentation and other topics as well.
• Jonathan Jesse (jjesse) – I’m to sexy for my docs, to sexy for my docs, so sexy they don’t validate! He got them in at the turn of the clock thankfully. I give him hell because I can, and because he does an amazing job with the Kubuntu chapter in the Official Ubuntu Book, which I am no longer a part of
• Carl Symons (kallecarl) – this guy is an editing ninja, so much so, I am giving him the title, Editor-In-Chief. My docs suck as it is, but thankfully he can unsuck them for me (that kind of sounded gross)
• Bhaskar Kandiyal (gastly) – holy smokes, this guy took on graphics and video and totally blew my mind. He actually taught me some Blender with his documentation. Rock on!

If you helped with something and I forgot your name, I truly do apologize. I just went with the list of names on our todo list. Everyone, if you run into any of these people on IRC, Ubuntu Forums, a mailing list, or anywhere, give them a hug, they truly do deserve it!

At the beginning of the Lucid cycle I put out a call-for-help on rewriting Kubuntu Documentation. It seems about 10 people were interested, and out of those 10, 4 or 5 stepped up to the plate and hit home runs. I truly am amazed just how wonderful our community is here. So, if you are interested in documentation (I am looking at you shadeslayer), hop in to #kubuntu-devel and #ubuntu-doc on freenode’s IRC service (see, I spelled it right, so don’t give me grief Nathan Handler!) and let us know. I am expecting to start documentation right around the beginning of Lucid+1, the Mighty Maltese (please use this, so my little Maltese will be happy).

My plans for Lucid+1 documentation, rewrite everything!

Just kidding. Add to what we have, change some formatting and layout stuff. So if you see it missing in Lucid documentation, please, fix it up and propose a merge and we will get it in! Thanks again to everyone who made kubuntu-docs a reality!

help:/kubuntu

Thanks to Silke “If it walks like a duck, talks like a duck, then it’s a duck” McCance for taking pictures during the entire weekend and uploading them.

The Official Pictures of the 2010 Desktop Help Summit.

What an amazing weekend! First off, I really want to thank the following people:

• Shaun “Is it Help? Hjelp? Yelp?” McCance – This entire event was his idea, his baby, and he pulled off one hell of an event. Thanks for showing off Mallard and Yelp.
• Kevin “Is my iPad here yet?” Harriss – The venue was hosted by Kevin at the always awesome IIT Institute of Design in downtown Chicago, IL. Also thanks for allowing me to crash on the futon.
• Jim “There are spy camera’s in my mansion” Campbell – Xfce and Xubuntu should be proud to have you on their teams, thanks for hosting that silly Brit Phil Bull and thanks for the coffee, donuts, and bagels.
• Milo “When the moon hits your eye like a big pizza pie” Casagrande – always good to see you again, and thank you for admitting that Italy could learn to make pizza from Chicago.
• John “Fedora has a bat cave” McDonough – Google thanks you for realizing you shouldn’t listen to me for directions, and it was great to get to hang out with some (somewhat) local Fedora peeps.
• Brian “GNOME is in the hizzy” Cameron – Thanks for spilling GNOME’s secrets so I can take them back to KDE Thanks for being a whicked cross-collab dude. Don’t think I didn’t hear you over there in the corner while I was writing American Idol’s next great hit!
• Phil “The Intern” Bull – Thanks for the surprise! It was awesome to finally meet you after working along side you for the past 5 years on the Ubuntu Documentation Project. I had no idea you were coming and then hearing some British voice yell my name in Chicago scared the hell out of me, I swore I paid those tickets, really I do!
• Silke “I’m with the Mallard” McCance – It was great to meet you, and great to see who it is that keeps Shaun in line Thanks for the spy videos of my computer voice song, and thanks for running across the street and picking up the utensils and drinks when there was free food, and thanks for getting Milo to admit that Chicago knows Pizza! Thanks for the coffee and bagels this morning too!

I would also like to thank Paul Cutler for trying to make it. I hope your family is feeling better, and I am sure this summer we can all get together for some documentation love!

So, the Desktop Help Summit 2010, the main reason for this post. We, members of GNOME, KDE, Ubuntu, Fedora, and Oracle/Sun/OpenSolaris, gathered in Chicago this weekend to hold the first, but hopefully not the last, Desktop Help Summit. It was all about collaborating on bringing help to our users and doing it better than everyone else. We collaborated, we learned, and we quacked! Heck, Shaun even gave the dancing Mallard some background music provided by Severed Fifth. Some of you who have followed me in the past know that for 3 years I chuckled at Project Mallard and called it nothing more than vapor-ware. Maybe I said it enough that Shaun, deciding to shut me up, has provided an amazing markup language specialized for topic-based help. If you doubt it for even a second, you should really see it in action. It is definitely something I would like to see make its way into the KDE SC one of these days. He showed off what he has been doing on Yelp 3.0, I think that is the version, that made be a bit envious and made me want something like it in the KDE SC.

To learn more about the event and what went on, check out the links to the people above, as I am sure they will post more information as well. I know John and Milo already have started blogging about it. There are pictures somewhere, as Silke was showin’ off her mad super camera skills. I really want a nice camera like that. I think Milo took some pictures and John has as well. Phil didn’t take any pictures because he was to busy looking up in the air at the tall buildings. We had to take him over to the zoo because he was missing the view of sheep on a daily basis, so to curb his home sickness, we looked out for him.

I also had some tweets (by @nixternal) and dents (by @nixternal) about the event as well. Thanks to those of you as well who participated on IRC. Notes are also available via Ether pad at http://etherpad.com/tUI4jbLm01 and http://etherpad.com/bnDi2pxN42.

Hey everyone, just wanted to drop a quick note to those of you who are in or around the Chicago land area, on Sunday, January 17th from 12:30PM until 5:30PM the Ubuntu Chicago LoCo team will be meeting up in Chicago for a documentation jam. If you would like to show up, here is the address of where we will be hanging out:

On-Shore Inc‎.
1407 W. Chicago Ave.
Chicago, IL

View Larger Map

If you can’t make it to the event, no worries, as you can join us on IRC in #ubuntu-chicago channel on the freenode IRC network. Plans are to work on Ubuntu, Kubuntu, and Xubuntu system documentation, as well as cleaning up the team wiki pages as well as community documentation on https://help.ubuntu.com/community.

If you plan on working on system documentation, here is what you can do prior to joining us on Sunday:

READ how we use the Bazaar repository for doing system documentation.

Ubuntu Documentation
Install build dependencies for the ubuntu-docs package:

sudo apt-get build-dep ubuntu-docs

Kubuntu Documentation
Install build dependencies for the kubuntu-docs package:

sudo apt-get build-dep kubuntu-docs

Xubuntu Documentation
Install build dependencies for the xubuntu-docs package:

sudo apt-get build-dep xubuntu-docs

Once you have done that, then you need to check out the latest documentation for Lucid for the documentation you are going to work on:

Ubuntu Documentation

bzr branch lp:ubuntu-docs

Kubuntu Documentation

bzr branch lp:kubuntu-docs

Xubuntu Documentation

bzr branch lp:xubuntu-docs

System documentation is in DocBook/XML format, which is a very simple markup language. Don’t worry if you really don’t know it as Jim Campbell and myself can quickly teach you what you need to know, in order for you to get up and running.

Don’t worry, if you don’t feel you are ready to work on system documentation, there is also plenty of wiki documentation that needs to either be cleaned up or added.

Hope to see you Sunday!

AWESOME! This definitely shows that the Kubuntu community has grown over the past couple of years, even among the complaints, we seem to be succeeding, and this makes me super happy. Just over a week ago, I decided that we were going to totally wipe out the current set of Kubuntu documentation and start from scratch. My buddy Jonathan Jesse, the 2nd Kubuntu docs dude, was freaking. He was like, “that sounds like a lot of work!” Oh, it did, but our awesome community has stepped up and is taking control, writing documentation, and good documentation at that. I am really grateful to all of you who are helping, and because of you, there is no doubt in my mind that our docs will finally kick ass again!

So, you keep hearing me talk about contributing to Kubuntu documentation, and you see that I say it would be nice for you to have some DocBook/XML experience. Many people want to help, but they don’t have that experience. In most cases, the people interested at least understand HTML or some other markup language a little bit. If you can understand that, then you can easily understand DocBook/XML the way we use it for Kubuntu documentation. DocBook/XML has a lot of tags that one can use, however we only use a very small subset of those tags with our documentation. Just an idea of the main tags we use from DocBook/XML are:

• <sect1>
• <sect2> – sometimes
• <title>
• <para>
• <ulink>
• <example> – sometimes
• <mediaobject> – only for screenshots
• <imageobject> – only for screenshots
• <imagedata> – only for screenshots
• <acronym> – sometimes
• <guibutton> – sometimes

There might be a few more, but these are the ones that pop into my head. For instance, when you are trying to let the reader know to open up an application via the menu, there is a tag called <menuchoice>. We have an entities file that contains all of the menu stuff, so you wouldn’t even need to use that tag, as you would call it in the document you are working in. Example: Say you are trying to tell the user how to open Amarok, you would enter &menuamarok;. Easy!

Here is an HTML example, lets say, Hello World

<html>
<head>
<title>Hello, World!</title>
</head>
<body>
<p>Hello, World!</p>
</body>
</html>

The html, head, and title, are already taken care for you with the template, so you just need to do the part in between the <p> and </p>. So in DocBook/XML, that would look:

<para>Hello, World!</para>

Easy. Typically with HTML, when you are trying to show a section or make a section stand out, you might use <h1> to make the title stand out. Well in DocBook/XML there are a few more lines, but still easy to do:

HTML:

<h1>This is the title of the section</h1>
<p>This is a paragraph in the section.</p>
<p>This is another paragraph in the section.</p>

DocBook/XML:

<sect1 id="intro">
<title>This is the title of the section</title>
<para>This is a paragraph in the section.</para>
<para>This is another paragraph in the section.</para>
</sect1>

If you are looking for a little bit more information concerning documentation in the Ubuntu world, take a look at the Documentation Team Wiki Page. There is also a bit of information on how we use Bazaar when working with documentation as well. To get an idea of how we use DocBook/XML with Kubuntu documentation, take a look at the old Jaunty Documentation for Kubuntu. Under the docs/ directory you will find the topics covered. And then under the topic, in the C/ folder is the XML markup for that topic. There is obviously a bit more DocBook/XML markup in our documentation, but the header portion and the layout is already completed in a template, so all one would need to do is fill in the space and create new sections.

If you have any questions, please do not hesitate to stop by the Ubuntu Documentation IRC channel on Freenode in #ubuntu-doc and ask away. We also have a mailing list where you can ask questions and communicate via email to other documentation people.