Ubuntu Open Week - Ubuntu Documentation Project - Wed, Nov 29, 2006

see also Saturday Session.

09:01   mdke    alright, thanks. Welcome everyone, I'm going to talk about Ubuntu documentation
09:01   mdke    I'll do a little introduction.
09:01   mdke    tell me if I go too fast
09:02   mdke    The documentation team is completely made up of volunteers. The core team is [WWW]  https://launchpad.net/people/ubuntu-doc but many others contribute to documentation all the time.
09:02   mdke    To find out how to communicate with us, see [WWW]  https://wiki.ubuntu.com/DocumentationTeam/Contact
09:02   mdke    The ultimate reference page for any information is [WWW]  https://wiki.ubuntu.com/DocumentationTeam
09:02   mdke    There are essentially two types of documentation that the team produces.
09:02   mdke    1. System documentation - this is written in a markup language called Docbook XML, and is hosted in our repository.
09:03   mdke    that's what you get when you click System->Help->System Documentation
09:03   mdke    2. Online documentation - composed of an html version of 1, and a community driven wiki ([WWW]  https://help.ubuntu.com/community)
09:03   mdke    clear so far?
09:04   mdke    ok. First I'll start by talking about 1. System Documentation
09:04   mdke    So, how can you contribute to these documents
09:04   mdke    Diving in and trying things out is the best way to begin getting involved.
09:04   mdke    Download our repository, and start getting familiar with the markup language by reading and editing some existing documents. We have a validation tool included which will tell you where there is an error in the document markup. If you are confused, you can ask in #ubuntu-doc or on the mailing list, and you will generally get some help, but you should be patient!
09:05   mdke    Low hanging fruit for those wishing to get involved:
09:05   mdke    Proof reading is a good way to get involved. Also, we have a number of bugs open about typos, errors, omissions, which you can try and fix. See [WWW]  https://launchpad.net/products/ubuntu-doc/+bugs and [WWW]  https://launchpad.net/distros/ubuntu/+source/ubuntu-docs/+bugs (in the latter link substitute ubuntu-docs with xubuntu-docs or kubuntu-docs if interested in that variant!)
09:06   mdke    We have some key tasks we want to look at for the next release of Ubuntu
09:06   mdke    these are:
09:06   mdke    1. Improving the navigability and readability of the help ([WWW]  https://wiki.ubuntu.com/TopicBasedHelp).
09:06   mdke    that's our major specification we're working on right now
09:06   mdke    2. #
09:06   mdke    2. Incorporating material from the Official Ubuntu Book into appropriate sections in the system documentation, amending the style accordingly.
09:06   mdke    3. Addressing areas which are missing from the documentation, in particular by reviewing material on the wiki/forum/mailing lists and converting it to docbook for inclusion in the system documentation (there is a good tool for doing this conversion).
09:07   mdke    4. Updating existing information which is no longer valid due to inclusion of new features in Feisty.
09:08   mdke    so that's a whistlestop overview of the system documentation. Does anyone have some questions specifically on that aspect of the documentation? Afterwards I'll talk about the community-driven wiki
09:08   mdke    but let's have a few questions now, otherwise I feel like I'm talking to myself...

[kudzubane] Is the HTML non-wiki documentation generated from DocBook as well?

• yeah. The material you see at https://help.ubuntu.com is simply an HTML version of our system documentation

[kudzubane] Is the documentation project also responsible for the Ubuntu book?

• no, we're not responsible for the book. That's done privately. it's under a free license, so as I mentioned, an important part of this release cycle will be dedicated to integrating it with the system documentation [Burgwork] no, the official ubuntu book is done by Prentice Hall and Canonical however, as mdke points out, it is under a free license

  [kudzubane] i seem to remember reading the book is done voluntarily

  • no, that's not correct: the authors are private individuals who are paid for it, but they are also community members but the documentation team isn't involved

[kudzubane] What tools are you currently using for producing system documentation?

• so, the tools. As I say, the markup is called docbook xml, which uses tags a bit like HTML. it can look quite complicated, but it is very easy to get a feel for how to add things. that's the basic tool.

[jmbuser] ok, more specifically, what editors do you use or is it a matter of personal taste?

• personal taste. I happen to like gedit myself bluefish can be nice too, and lots use emacs/vi/nano/whatever

[apokryphos] Quanta+ is very good for docbook, too (just a note that http://quanta.kdewebdev.org/tutorials/quanta-docbook/quanta.html had a good docbook+quanta howto)

• [Burgwork] the Kubuntu peope use kate as well [jonathan_] nano is always usefull (not great, but usefull)

  [jmbuser] Last part: Do you use any specific gedit plugin?

  • no, I don't use any plugins.

09:15   mdke    ok, any other questions on the system documentation? I should probably mention translation, which is a key task too
09:16   mdke    the documentation gets translated using Rosetta, in the same way as other Ubuntu programs

[teprrr] are you translation documentation for non-ubuntu related stuff too? if so, it'd be nice to have those translations to upstream too..

• no, as far as I know, no upstream documentation is translated in Rosetta.

[mihakriket] Is thier a template for the docs?

• we have a couple of templates yes. They are in our repository under incoming, see for example: https://docteam.ubuntu.com/repos/trunk/incoming/. however the best way to work is to simply open up an existing document and explore that. one very important thing to emphasise. if people don't understand how to use docbook, we'll accept input from anywhere: bug reports, mailing list, wiki articles, and so on

09:21   mdke    that brings me on nicely to the wiki material, so I'll explain that, then take more questions
09:22   mdke    so this is the wiki at https://help.ubuntu.com/community
09:22   mdke    to contribute:
09:22   mdke    Simply log into the wiki (using your launchpad account), and correct errors you find in documents. Read existing documents to become familiar with the wiki markup, which is very simple. Above anything else, read the wiki guide: [WWW]  https://help.ubuntu.com/community/WikiGuide.
09:23   mdke    a good guide to our wiki markup is at https://help.ubuntu.com/community/HelpOnEditing
09:23   mdke    it's very simple.
09:23   mdke    Low hanging fruit for those wishing to get involved:
09:23   mdke    One way of becoming familiar with the material and how we work is to begin reading it and checking it for accuracy. Report any bugs at the above links!
09:23   mdke    A number of more substantial "wiki-tasks" (as well as a list of pages that need serious attention) are listed on [WWW]  https://help.ubuntu.com/community/WikiToDo.
09:24   mdke    The key tasks for improving the wiki over the next release are:
09:24   mdke    1. Improve the self-maintainability of the wiki by introducing easy tools for quality assurance ([WWW]  https://wiki.ubuntu.com/HelpWikiQualityAssurance). This spec needs ideas, discussion and eventually some code!
09:25   mdke    2. Once we have a nice system in place, doing quality assurance to ensure users are given reliable information and can quickly identify how reliable a page is.
09:25   mdke    3. Improving existing material and adding new material to the wiki, in particular drawing on the immense resources offered by the forums ([WWW]  https://help.ubuntu.com/community/forum)
09:26   mdke    4. Clarify the license of material on the wiki by convincing the Community Council to approve the year-old specification ([WWW]  https://wiki.ubuntu.com/WikiLicensing).
09:27   mdke    (there are quite a lot of links in this presentation, I'll make some notes available so that people can read over them and take in the pages I've linked to with a bit more time)
09:27   mdke    A long-term goal (at least for me) is to bring the system documentation and the online documentation closer and closer together, so that eventually it is easy for the system documentation to draw on contributions via the wiki,
09:27   mdke    and (the other side of the coin) users to browse and search all of the available documentation via a single interface, be it via the online website or the system help viewer. This goal is rather a large one, and is essentially waiting on the right tools to come together.
09:28   mdke    Ok. That was a quick summary of the wiki documentation material we have. I've come to the end of my prepared presentation, so we can dedicate the rest of the session to questions.
09:29   mdke    feel free to post questions in here, but please wait until I've answered the previous question. Who's first?

[mihakriket] To edit the documents on the wiki, do you need to be a member of the docs team?

• mihakriket: absolutely not. You need to log in, and then you can go ahead and edit. If you are making structural or seriously large changes, it's a good idea to discuss them on the mailing list, but otherwise, basically free reign at this time

<KHatfull> Are proper backup/restore/disaster recovery procedures/documentation something being looked at?

• no, we don't have any system documentation about that. It would be a nice thing to include. There may be material on the wiki, if so, then maybe it can be tidied up and transformed into something that can be included in the system documentation. if you're interested in working on that, that would be great. If not, you can open a bug and hopefully someone will be inspired to look at that area

[daxelrod] What level of expertise are assumed of the reader of documentation? Or does it depend on what is being documented?

• good question. yes, to some extent it depends on what is being documented. We tend to try and assume the level of expertise is something around what we envisage as being the level of the average Ubuntu user. so we try and make it as easy to understand as possible, even for someone who is new to Ubuntu but we tend to assume some experience with computers. some documents cover the basics, and others more advanced subjects, of course [Burgwork] we also assume that the reader is more familar with and more comfortable with graphical tools

09:41   mdke    cool. Anyone else have some questions? Are people reading interested in improving documentation in Ubuntu?
09:41   mdke    we could sure use some help, and it's a great way of getting involved in Ubuntu for newcomers and experienced users alike

[dnkorte] if someone wanted to get involved in proofreading, whom does he contact?

• our mailing list is a great place to start. and diving in

  [dnkorte] where to signup for mailing list?

  • https://wiki.ubuntu.com/DocumentationTeam/Contact

[lazywanker] sorry if this has been covered already. how are k/x/ed/ubuntu specific docs integrated with the ubuntu (read: gnome) docs. is there a section for the ubuntu-common stuff that covers all distros?

• some material is common between the distributions. For example the server material, packaging guide, and the desktop based material is kept as similar as possible. x/ed/ubuntu do not have very much overlap, to my knowledge

[violot] Where do you need help in the docs the most? Or what do you need help on... etc.

• that rather depends on whether you are interested in contributing on the wiki or to the system documentation. I mentioned some key tasks during the presentation. I won't repeat them here, but I'll make my notes available on the mailing list, on the wiki and on my blog

[lazywanker] wrt to previous question. surely then you're going to get alot of overlap and/or people having to hunt in two places for an answer?

• can you explain what you mean in a bit more detail?

  [lazywanker] bob wants to know how to do job x in kubuntu. job x can be done in a number of ways, via cli, via guis in the various DEs. bob doesn't know if he should hunt through the ubuntu wiki/help, the kubuntu wiki/help or what? each place offers different methods. obviously the gui stuff is different but the cli stuff is too since they are completely seperate. how does he know which is 'right'?

  • since Bob uses Kubuntu, he should use the Kubuntu help system (where the shared material appears, as well as Kubuntu-specific material). As for online material, Kubuntu and Ubuntu share the same online website.

[mihakriket] I would be interested on working on the wiki. I sometimes have time @ work to go online.

• that would be great. https://help.ubuntu.com/community/WikiGuide and https://help.ubuntu.com/community/WikiToDo are the key pages

  [daxelrod] The hardest part for me in learning about Ubuntu has been going from some aspect of the integrated system to the name of that component. Is there some index that maps one to the other? (Example: LiveCD Installer <-> Ubiquity) no, to my knowledge there isn't any such material. Usually, that's more of a task for people interested in contributing, rather than for users, who often don't need to know the names of programs

  [daxelrod] That's my main problem, I'd like to go from user to contributor. And I'm sure many others would as well.

  • ask ask ask is the answer in irc channels, mailing lists, and so on

[violot] Got a link to your weblog? I'm not familiar with you, don't think I've seen you before :)

• it's at http://www.mdke.org

[thebigearl] I want to help translating the system documentation to german. how can i do that?

• all you need to know is how to use the [WWW] Rosetta translation system. You can find out how to use that on the Rosetta wiki page. Once you have learnt all of this, the docteam documents can be found in several places:

  • [WWW] https://launchpad.net/distros/ubuntu/dapper/+source/ubuntu-docs,

    [WWW] https://launchpad.net/distros/ubuntu/dapper/+source/kubuntu-docs,

    [WWW] https://launchpad.net/distros/ubuntu/dapper/+source/xubuntu-docs.

[daxelrod] Has vandalism been a problem with the documentation wiki? I could see somebody replacing useful instructions with instructions to trash the system, for example.

• no, so far it hasn't. People tend to keep an eye on key pages, and we haven't experienced serious problems. the wiki software has some access control systems which we can use if problems arise, but so far it hasn't been necessary. [Burgwork] we also disallowed anon edits, which removes some of the driveby vandals

09:56   mdke    we'll answer any questions you think of on the mailing list, and in our irc channel. We'd also be very interested in ideas and feedback you have
09:57   mdke    ok, if no one has any last questions, we'll pass onto the next session