DocTeam

Revision 8 as of 2007-10-27 17:29:32

Clear message

Who am I?

My name is Richard Johnson. I am an Ubuntu member as well as a member of other teams within the Ubuntu community. I am known mostly around here as the Kubuntu and KDE documentation guy. So because of this, I will be talking to you all today about the Ubuntu Documentation Project.

What is the Ubuntu Documentation Project?

The project was created in order to create system documentation for the Ubuntu operating system. As time went on and Ubuntu matured, the scope of the project has widened. Currently the Ubuntu Documentation Project encompasses everything from the wikis to system documentation for each Ubuntu partner project (Kubuntu, Edubuntu, and Xubuntu).

Who is the Ubuntu Documentation Project?

The project is comprised of the Ubuntu Documentation Team which is completely made up of volunteers. The core team is https://launchpad.net/~ubuntu-doc however many others contribute freely to the documentation all the time. The core team spends a majority of their time working on system documentation whereas the volunteers tend to start off adding documentation to the community wiki (https://help.ubuntu.com/community) and eventually work their way up to the core team.

What types of documentation does the team work on?

There are essentially two types of documentation that the team produces.

  1. System documentation - this is written in a markup language called DocBook/XML, and is hosted in the documentation repository.

  2. Online documentation - composed of an HTML version of #1, and a community driven wiki (https://help.ubuntu.com/community).

Why are there 2 wikis?

  • https://wiki.ubuntu.com is looked at mainly as the developer wiki. This wiki is meant to store specifications and team information as well as personal wiki pages for members and future members.

  • https://help.ubuntu.com/community is the community documentation wiki. Any and everyone is more than welcome to add their documentation to that wiki, or improve the documentation that is already there. This is the wiki to go for when you need help with your system.

How does one contribute to the project?

Diving in and trying things out is the best way to begin getting involved. If you have edited a ton of wiki pages, or have experience with technical documentation, then maybe you should go ahead and download our repository (https://wiki.ubuntu.com/DocumentationTeam/Repository) and start getting familiar with DocBook/XML and the way we rock.

We have even included a validation tool in our repository to help you ensure the documentation you have created is logically valid. If you are confused or have any questions, please feel free to ask in #ubuntu-doc or on the mailing list (ubuntu-doc@lists.ubuntu.com). Be patient, as sometimes the IRC channel may be dead, however the mailing list is usually quick to provide a response.

What is this DocBook/XML you keep blabbing about?

DocBook is a DTD (Document Type Definition) which includes a very popular set of tags for describing books, articles, and other prose documents. XML (eXtensible Markup Language) is a general purpose, free and open source, markup language. Both are fairly easy to pick up and learn. More information on DocBook is available at http://docbook.org/tdg/en/html/docbook.html.

I am not all up technically enough to document, what else can I do?

Proof reading is a great way to get started as well. This will not only find our mistakes, but it will allow you to familiarize yourself with the ways that we do things. You can look through our documentation via the repository, or by visiting http://doc.ubuntu.com and reading through the documentation that gets built nightly via the repositories. Note this is a staging area and not a final release area.

Also note the wiki sections below.

What are the key tasks with the documentation team?

There are actually quite a few tasks, and they continue to grow with each release. So due to this, we definitely have the need for more contributors. As it stands, these are just some of the key tasks:

  • Improving the navigability and readability of the help (https://wiki.ubuntu.com/TopicBasedHelp)

  • Incorporating material from the Official Ubuntu Book into appropriate sections in the system documentation, amending the style accordingly.

  • 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.

  • Updating existing information which is no longer valid due to inclusion of new features in each release.

Wiki Documentation

Contribution is as easy as logging into the wiki using your launchpad account, and then correct the errors you find in the documents. Read existing documents to become familiar with the wiki markup which is very easy to do. Some of you may have noticed = Question =, that is wiki markup which is similar to the <h1> or main header in HTML.

The community documentation wiki also needs a little spring cleaning as well. So you can visit https://help.ubuntu.com/community/CategoryCleanup and go through and proof the pages, and make them conform to the Wiki Guide at https://help.ubuntu.com/community/WikiGuide. After you have edited and cleaned up a few pages, apply to join the Wiki Team at https://beta.launchpad.net/~ubuntu-wiki.

Is there any one task you really need help with on the wiki?

Cleaning out the CategoryCleanup category on the wiki is a big task for wiki pages at this time. You can see which documentation is in need of some cleaning. Refer to the previous topic under Wiki Documentation.

Like system documentation are there key tasks for the wiki?

Sure there are. Here are just a few of them now:

  • Improve the self-maintainability of the wiki by introducing easy tools for quality assurance (https://wiki.ubuntu.com/HelpWikiQualityAssurance). This spec needs ideas, discussion and eventually some code.

  • Doing quality assurance to ensure users are given reliable information and can quickly identify how reliable a page is.

  • Improving existing material and adding new material to the wiki, in particular drawing on the immense resources offered by the forums (https://help.ubuntu.com/community/forum).

A main goal is to bring the system documentation and the online documentation closer and closer together, so eventually it is easy for the system documentation to draw on contributions via the wiki, and 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 is a very large goal awaiting the right tools to come together.

TRANSLATIONS!!!

No question really, but I don't know if you all realize this or not, but translators are one of the largest assets of the Ubuntu community. Ubuntu is known as an operating system with more translations than any other. We can never have enough truthfully, so if you are a translator and are interested in helping out, then you just need to learn the Rosetta translation system (https://launchpad.net/rosetta).

You can find out how to use that on the Rosetta wiki page (https://wiki.ubuntu.com/Rosetta). Once you have brushed up on all of this, the docteam documents can be found at https://launchpad.net/distros/ubuntu/hardy/+source/ubuntu-docs. Replace ubuntu-docs with kubuntu-docs, xubuntu-docs, and/or edubuntu-docs accordingly.

Conclusion

Thank you for staying awake during this little speech. I hope I was able to provide you with viable information to help you get started. If you come up with any questions, any problems, or whatever, please feel free to contact me anytime (nixternal@ubuntu.com). To contact the team try any of the following:

The floor is now open for questions. Please join #ubuntu-classroom-chat if you haven't already and prefix your questions like => QUESTION: I heard Matthew East is really a documentation robot, is this true?

Thanks again everyone!

Questions from the audience

  • QUESTION: What do you mean by 'logical validation' for the doc umentation? Syntax?

    • ANSWER: what the tool does is it goes through the xml document and makes sure that you have properly coded the markup. For instance the following is logically incorrect:

      • The reason being that when you do a <sect1...> you need to follow it with a <title>Woohoo</title> prior to the <para></para> tags. now this validation tool checks all of the tags and prints out to the screen (i.e. terminal) all of your validation errors. The reason we validate is to ensure that the documentation will get built correctly to HTML for one, and two that when you look at the documentation via Yelp it will be formatted correctly and unbroken 

<sect1 id="test">
<para>Ubuntu Rocks!</para>
</sect1>

  • QUESTION: Is there a WYSIWYG Dockbook editor?

    • ANSWER: None that I know of unfortunately. The popular editors currently are: gEdit, Kate (has a great XML validation tool built in), Bluefish, Quanta, Komodo (this is a new FREE editor that totally rocks), and truthfully any text editor. Emacs and Vim both have great DocBook/XML extensions that will highlight, indent, and some will even word complete as you type.

  • QUESTION: Is translating the docs different from translating applications (whole text vs. string by string)?

    • ANSWER: Documentation translation will occur on a paragraph or line-by-line occurance or as you said string-by-string. From what I have heard it isn't all that time consuming, but it is somewhat tedious.

* QUESTION: So you say Docbook ist for system documentation and wiki.ubuntu.com is for system documentation; help.ubuntu.com/community is for other documentation - so is wiki.ubuntu.com written in Docbook?

  • ANSWER: wiki.ubuntu.com is really for developer documentation. It used to host all documentation, but it became confusing to new users, then again so did adding help.ubuntu.com/community. All of our wikis, which are MoinMoin powered, use a wiki syntax or markup. this syntax/markup is way different, and actually much easier than DocBook/XML. System documentation is all DocBook/XML, and when I say system documentation I mean what you see when you fire up KHelpCenter in Kubuntu, or Yelp in Ubuntu/Xubuntu/Edubuntu. In Kubuntu, we have to build out the XML files we create to HTML, whereas with Yelp it will read .xml files natively. The following is a quick example of wiki markup 

= Hello Monika|K = would create a level 1 heading on the wiki
* This would be a list unorganized list item (i.e., <ul><li>foo</li></ul>)

  • QUESTION: Is it a good idea to translate using some service like Babelfish and a spell checker and correcting the remaining errors/untranslated bits or does that have copyright/other issues? Or is it actually slower than doing it manually?

    • ANSWER: I don't think copyright would be an issue with this. Canonical has done a great job in creating the Rosetta system for Launchpad, and since Ubuntu does it, we kind of follow suit. I know that the KDE community utilizes Babelfish with KBabel and they also do a great job with translations. Time wise I would think it is about the same, because a Babelfish editor and the Rosetta interface actually break down the .pot files the same, .pot files being the translation files created using the xml2po command

  • QUESTION: Where does one upload/edit the system documentation?

    • ANSWER: all of our system documentation is located in a Subversion (SVN) repository at https://docteam.ubuntu.com/repos. Under the branches/ directory you will find all of our already released documentation. Under the trunk/ directory you will find all of the current development documentation that is being worked on, in this instance trunk/ is for 8.04 documentation (Hardy). You can use either Subversion from the command line or use a Subversion GUI client. To check out our trunk documentation, ensure you have subversion installed.

Quick tutorial

If you want to work with the Ubuntu system documentation, here is what you need to do. First things first...You need the applications which the ubuntu-docs depend on. So to get these in one shot, at the command line type the following: 

sudo apt-get build-dep ubuntu-docs

This will pull in all of the necessary docbook, xml, poxml, applications and such. To see which each application does, type: 

apt-cache show application_name

Now to download, or checkout our repository, get to a directory where you want to save the checkout too, in my case I use /home/nixternal/ubuntu/docs/repos/. So once I am there, I do: 

svn co https://docteam.ubuntu.com/repos/trunk

That will create a trunk/ directory in my current directory which I listed above, and in that trunk directory will be everything you need to work on with Ubuntu, Kubuntu, Xubuntu, and Edubuntu documentation more information about our repository can also be read up on at https://wiki.ubuntu.com/DocumentationTeam/Repository

Logs and Q&A

Hardy

Log

To Come...

Q & A

To Come...

Gutsy

Log

Q & A

  • QUESTION: Will Kubuntu be able to natively read .xml in the future?

    • ANSWER: Kubuntu uses the KDE help center known as KHelpCenter. It can read .docbook files natively with no problem. So either we can continue building the documentation out to HTML, or we could convert to .docbook filetypes in the future, in which this is being looked into for Gutsy development

  • QUESTION: Can everybody contribute to the system documentation?

    • ANSWER: YES!!! but... Unless you have commit rights on the Subversion repository, you cannot commit directly to the repo. However with Subversion (and Bazaar is we ever switch to it in the future) allows you to create patches very easily. When you have downloaded/checked out from the repository, you can make changes to the .xml files locally on your system and when you are happy with your changes/fixes, and have ensured they do validate using the validation tool, you can create a quick patch file. To do this you would simply type: 

svn diff > foo_is_bar.diff
  • to make sure you are going to get the correct changes, it is best to run 

svn stat

first to see what all changes you are looking at. Now if you made changes in trunk/kubuntu/libs and you were in the trunk/ubuntu directory and ran svn stat or svn diff, you wouldn't get anything. So what I recommend is to change to the root directory of the repository checkout (trunk/) and svn stat}} and then {{{svn diff. Now once you have the diff/patch file created, simply email it to ubuntu-doc@lists.ubuntu.com and a person with commit rights will check it over and if everything is good to go, commit it to the repository. To get commit rights, after you have submitted a few patches which shows that you know what you are doing, and you know your way around Subversion, Matthew East will bug Canonical and tell them to add an account for you.

  • QUESTION: Are the build-deps different for kubuntu docs? 'gnome-doc-utils' is a build-dep for ubuntu-docs, but I would doubt it's required for KDE...

    • ANSWER: It isn't required for KDE, you are correct, however ubuntu-docs contains all of the tools necessary for kubuntu-docs as well. If you are unsure, it would never hurt to run: 

sudo apt-get build-dep kubuntu-docs

  • QUESTION: Why doesn't the doc team switch to bazaar?

    • ANSWER: the Subversion repository works! We do have a Bazaar sandbox and as soon as some little quirks are worked out with Bazaar, I am sure we will switch eventually. When? I can't give you a timeline on that. I am sure we will all meet and talk with the LP and Bazaar gurus and work it out then, until then, svn is it for docs.