Ubuntu Open Week - Documentation team - Rich Johnson - Fri, Apr 27, 2007
TZ UTC-4
(04:02:17 PM) nixternal: OK, here we go. I have created a wiki page for this talk located at https://wiki.ubuntu.com/RichardJohnson/OpenWeekDocTeamNotes (04:02:45 PM) nixternal: here we go! (04:02:47 PM) nixternal: = Who am I? = (04:02:48 PM) nixternal: 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. * Wiki Page: https://wiki.ubuntu.com/RichardJohnson * LP Page: https://launchpad.net/~nixternal (04:03:17 PM) nixternal: copy/paste worked great there :) (04:03:32 PM) nixternal: = What is the Ubuntu Documentation Project? = (04:03:36 PM) nixternal: 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). (04:04:08 PM) nixternal: = Who is the Ubuntu Documentation Project? = (04:04:08 PM) nixternal: 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. (04:04:12 PM) nixternal: 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. (04:04:45 PM) nixternal: = What types of documentation does the team work on? = (04:04:48 PM) nixternal: 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). (04:05:34 PM) nixternal: = 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. (04:05:38 PM) nixternal: * 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 documentatiton that is already there. This is the wiki to go for when you need help with your system. (04:06:33 PM) nixternal: = How does one contribute to the project? = (04:06:36 PM) nixternal: 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. (04:07:02 PM) nixternal: 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. (04:07:56 PM) nixternal: = What is this DocBook/XML you keep blabbing about? = (04:07:59 PM) nixternal: 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. (04:08:50 PM) nixternal: Addon: For those of you familiar with HTML will pick up XML and DocBook fairly easy. Those of you without HTML experience will probably tend to pick it up a little easier (04:09:20 PM) nixternal: Addon: The reason being you won't confuse the markup tags between the two since there are at times some similarity. (04:09:36 PM) nixternal: = I am not all up technically enough to document, what else can I do? = (04:09:40 PM) nixternal: 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. (04:09:46 PM) nixternal: Also note the wiki sections below. (04:09:53 PM) nixternal: well in this case, the wiki sections coming up :) (04:10:29 PM) nixternal: = What are the key tasks with the documentation team? = (04:10:31 PM) nixternal: 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: (04:10:43 PM) nixternal: * Improving the navigability and readability of the help (https://wiki.ubuntu.com/TopicBasedHelp) (04:10:53 PM) nixternal: * Incorporating material from the Official Ubuntu Book into appropriate sections in the system documentation, amending the style accordingly. (04:11:04 PM) nixternal: * 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. (04:11:13 PM) nixternal: * Updating existing information which is no longer valid due to inclusion of new features in each release. (04:11:41 PM) nixternal: Addon: Of course there is more as the community matures, but these are just a few of our more popular and frequented tasks. (04:11:54 PM) nixternal: lol (04:12:25 PM) nixternal: time for everyons favorite, the Ubuntu wiki(s)! (04:12:35 PM) nixternal: s/everyons/everyones/ (04:12:41 PM) nixternal: = Wiki Documentation = (04:12:43 PM) nixternal: 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. (04:13:28 PM) nixternal: Addon: or <sect1 id="ubuntu-documentation-rocks" status="perfecto"> :) (04:13:48 PM) nixternal: that was for you XML and DocBook fans right there. Which I see maybe 1 or 2 of :) (04:14:03 PM) nixternal: 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. (04:14:57 PM) nixternal: = Is there any one task you really need help with on the wiki? = (04:14:59 PM) nixternal: 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. (04:15:39 PM) nixternal: Addon: *ALL* community documentation concerning the binary drivers, such as ATI and NVidia, definitely need some love. (04:16:10 PM) nixternal: Addon: Each one of those documents present a number of confusing methods for users who are not only new to Ubuntu, but also to Linux in general. (04:16:52 PM) nixternal: Addon: WiFi is another section of concern, seeing that there are also many different ways to skin the same cat. (04:17:38 PM) nixternal: Addon: We need dial-up modem experience and documentation as well. The documentation on the wiki currently is very limited. Granted linmodems website contains a lot of the necessary information, just not in an Ubuntu way. (04:18:01 PM) nixternal: = Like system documentation are there key tasks for the wiki? = (04:18:01 PM) nixternal: Sure there are. Here are just a few of them now: (04:18:10 PM) nixternal: * 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. (04:18:26 PM) nixternal: * Doing quality assurance to ensure users are given reliable information and can quickly identify how reliable a page is. (04:18:42 PM) nixternal: * 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). (04:19:44 PM) nixternal: Addon: This is where my previous addons come into play. The better our documentation, community wiki wise, the easier it is for a new user to switch as seemlessly as possible. With your help, I am sure this can be achieved. (04:20:08 PM) nixternal: 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. (04:21:21 PM) nixternal: Addon: The Documentation Team would love to hear ideas on how something like this could be achieved easily, but at the same time have the best functionality, accessibility, and usability one would come to expect from Ubuntu. (04:21:39 PM) nixternal: ubuntu-doc AT lists DOT ubuntu DOT com is a great place to get your ideas heard! (04:22:00 PM) nixternal: = TRANSLATIONS!!! = (04:22:03 PM) nixternal: 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). (04:23:21 PM) nixternal: Addon and Note: If you notice that some translations are lacking with the 7.04 release, that is in now way a reflection on our translators. During the development phase, it took a little longer to get Rosetta and the Launchpad working correctly due to new technology being implemented. (04:23:59 PM) nixternal: Addon: I would definitely like to thank all of those who helped with translations during the short translation period for 7.04. They rocked hard and fast! I couldn't have asked for more. (04:24:10 PM) nixternal: 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/gutsy/+source/ubuntu-docs. Replace ubuntu-docs with kubuntu-docs, xubuntu-docs, and/or edubuntu-docs accordingly. (04:24:51 PM) nixternal: Note: The Gutsy translations will of course not be available until later in the development cycle (04:25:14 PM) nixternal: Note: So if you go there now, I believe it may either give you an Oops or redirect to Feisty translations. (04:25:45 PM) nixternal: = Conclusion = (04:25:46 PM) nixternal: 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 AT ubuntu DOT com). To contact the team try any of the following: (04:25:57 PM) nixternal: * IRC - server: chat.freenode.net - port: 8001 - channel: #ubuntu-doc (04:26:10 PM) nixternal: * Mailing List - ubuntu-doc@lists.ubuntu.com - subscribe or read the archives at https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc. (04:26:15 PM) nixternal: * Wiki - https://wiki.ubuntu.com/DocumentationTeam (04:26:22 PM) nixternal: 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? (04:26:26 PM) nixternal: Thanks again everyone! (04:26:48 PM) nixternal: ANSWER: I still don't know truthfully :)
[ samgee] QUESTION: What do you mean by 'logical validation' for the documentation? Syntax?
- what the tool does is it goes through the xml document and makes sure that you have properly coded the markup. For instance:
<sect1 id="test">
<para>Ubuntu Rocks!</para>
</sect1>
that 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
[ samgee] QUESTION: Is there a WYSIWYG Dockbook editor?
- 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.
[ samgee] QUESTION: Is translating the docs different from translating applications (whole text vs. string by string)?
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. I don't know translations 100%, except for the fact that I manually upload them from time-to-time, hopefully not irritating anyone
[ Monika|K] QUESTION: So you say Docbook is 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? :confused:
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. = 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>). 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. I apologize for the confusion there
[ samgee] 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?
- 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
[ Monika|K] QUESTION: Where does one upload/edit the system documentation?
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 7.10 documentation (Gutsy). 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
(04:45:28 PM) nixternal: OK, Quick tutorial time!!! (04:45:40 PM) nixternal: If you want to work with the Ubuntu system documentation, here is what you need to do (04:45:56 PM) nixternal: I apologize as I will be covering it from a command line perspective since that is what I do daily :) (04:46:29 PM) nixternal: 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 (04:46:37 PM) nixternal: sudo apt-get build-dep ubuntu-docs (04:47:00 PM) nixternal: this will pull in all of the necessary docbook, xml, poxml, applications and such (04:47:06 PM) nixternal: to see which each application does, type (04:47:19 PM) nixternal: apt-cache show application_name (04:47:40 PM) nixternal: now to download, or checkout our repository, get to a directory where you want to save the checkout too (04:47:55 PM) nixternal: in my case I use /home/nixternal/ubuntu/docs/repos/ (04:48:02 PM) nixternal: so once I am there, I do: (04:48:20 PM) nixternal: svn co https://docteam.ubuntu.com/repos/trunk (04:48:28 PM) nixternal: that will create a trunk/ directory in my current directory which I listed above (04:48:51 PM) nixternal: and in that trunk directory will be everything you need to work on with Ubuntu, Kubuntu, Xubuntu, and Edubuntu documentation (04:49:13 PM) nixternal: more information about our repository can also be read up on at https://wiki.ubuntu.com/DocumentationTeam/Repository
[ samgee] QUESTION: Will Kubuntu be able to natively read .xml in the future?
- 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. This is being looked into for Gutsy development.
[ Monika|K] QUESTION: Can everybody contribute to the system documentation?
YES!!! WOOHOO! but... you knew that was coming.
unless you have commit rights on the Subversion repository, you cannot commit directly to the repo, but, 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. 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 or 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.
[ ryanakca] 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...
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 I believe the main files you need would be the docbook-xml (which I messed up recently and didn't have build-deps in the package for kubuntu), xml2po, libxml stuff and what not. which I believe most is installed ootb with the Ubuntu projects
[ ryanakca] QUESTION: Why doesn't the doc team switch to bazaar?
oh man, I will get killed if I don't answer this one correctly, so remind me when I meet you one day ryanakca to repay you for this one
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. 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
[ ryanakca] Build-Depends: debhelper (>= 5.0.0), cdbs, xsltproc, docbook-xsl, docbook-xml, perl, perl-modules, kdelibs-data, kdelibs-bin
- not a question, but definitely needs an explanation. debhelper and cdbs aren't really needed as they are for packaging purposes only. *xsl and *xml are definetly needed. perl and perl-modules are so that we can use the firefox-translation script (python anybody?)
(05:01:14 PM) nixternal: I think that is about it, time is up (05:01:28 PM) nixternal: any questions, I live in #ubuntu-doc, email me at nixternal@ubuntu.com (05:01:32 PM) nixternal: ubuntu-doc AT lists DOT ubuntu DOT com (05:01:41 PM) nixternal: https://wiki.ubuntu.com/DocumentationTeam (05:01:52 PM) nixternal: thanks again everyone for listening in!