Friday, September 16, 2011

New Thing: Kubuntu Documentation

For about a year I've been intending to contribute to Kubuntu Documentation, beyond the occasional update or correction of the wiki -- not that that isn't important too! But the docs which are distributed (accessed through the Help menu or F1) with all of our applications are the basic way we interact with our users all over the world. As the applications change and our settings, and suite of applications change over time, the documentation needs to be kept both current and correct. This is the role of the Documentation team. Once we're done, the docs are turned over to the Translation team, who are heroes!

Since David Wonderly (DarkwingDuck in IRC) took the leadership of the team, he's created a nice guide to contribution, at As I discovered during crunch time, it wasn't perfect - by the time you consult it, it will be, I'm sure!

One thing which was not stressed to me, and turned out to be important, was pulling to keep the update current. If you are working in a team, it's important to do this step frequently so that you are working on current copies of the documents.

David has documented the steps well, so I don't need to go through them here, but as in any technical process, it's important to set up your process and follow that faithfully. So always update before uploading (pushing), always fix conflicts first, and so forth.

Also, communication is important. We use a Whiteboard on Launchpad, and I discovered that I wasn't saving after claiming work items. There is no SAVE button -- just a green checkmark. Use the green checkmark! And talk to people in IRC about your intentions as well. Stepping on someone's work makes two unhappy people, and wasted worktime as well.

To sum up, getting started in Kubuntu/Ubuntu documentation involves some technical steps, such as setting up Bazaar and your SSH key, getting the Repository branch(es) you'll be working with, and keeping them up-to-date. However, they are clearly described, and help or hand-holding is available on IRC. Just follow the steps as described, and you'll have success, as I did.

The documents themselves are edited in a text editor (I use Kate, naturally), saved as usual, then committed locally, and finally pushed to Launchpad. Once uploaded, they can be checked by one of the developers and committed on Launchpad. Once you have pushed, remember to update your status on the Whiteboard, and mention it on IRC as well, if you are working in a team. #kubuntu-devel for Kubuntu, and #ubuntu-doc for everybody.

Finally, thanks for contributing to documentation! Your fellow users thank you.


  1. Big thanks for helping out with things this cycle. Maybe next cycle we cna get you access to core-doc which gives you contribution rights.

    I'll keep sponsoring your patches all day long :)

    Also you can keep changing things and then push up once we have P open for dev

  2. Valorie, I know that there were some frustrating conflicts of work at 3am on crunch day... That being said thank you so much for all of the hard work you poured into the docs and I know I keep saying this but, next cycle we will have a better stream of what goes on. (Admittedly this cycle was better then last.)

    Thanks again for all of you hard hard work!