== Ubuntu Open Week - Ubuntu Documentation Project - Jordan Mantha - Fri, May 2, 2008 == {{{ === jcastro changed the topic of #ubuntu-classroom to: Ubuntu Open Week | Information and Logs: https://wiki.ubuntu.com/UbuntuOpenWeek | How to ask questions: https://wiki.ubuntu.com/UbuntuOpenWeek/Rules | Ask questions in #ubuntu-classroom-chat, prefaced with "QUESTION:" |See https://wiki.ubuntu.com/UbuntuOpenWeek/JoiningIn to filter out channel noise | "Ubuntu Documentation Project" - Jordan Mantha [21:56] Unfortunately Richard Johnson has a power outage, so Jordan Mantha, aka LaserJock will be filling in [21:56] In about 5 minutes. :D [22:00] ok LaserJock, take it away! [22:00] ok people, time to get excited! [22:00] My name is Jordan Mantha and I'm a volunteer developer for Ubuntu [22:01] today I'm going to give you a brief intro to the Ubuntu Documentation Project and then open it up for a Q&A time [22:01] The Doc Team is an all-volunteer army of people with a variety of technical abilities and backgrounds [22:02] with the goal of providing first-class system documentation for Ubuntu, Kubuntu, Xubuntu, and Edubuntu [22:02] as well as trying to calm the chaos that is the Ubuntu wikies [22:03] we have a core set of team members that have write access to the system documentation that is housed in bzr branches on Launchpad [22:04] the system documentation is written in docbook for people who care :-) [22:04] but we also have a DocuMENTORs program for people who want to get mentored into the team [22:04] and they can join a Documentation Students team [22:05] https://launchpad.net/~ubuntu-doc/+members gives an overview of the teams [22:05] https://wiki.ubuntu.com/DocumentationTeam is a general intro to what we work on [22:05] and https://wiki.ubuntu.com/DocumentationTeam/Mentoring talks about the mentoring program [22:06] are there any questions at this point? [22:07] QUESTION: Why should people care about docbook? [22:08] well, docbook has lots of advantages, and some disadvantages [22:08] docbook is nice because it has a fairly simple, XML, syntax [22:08] if you know any HTML you can pick it up easily [22:09] it's also built specifically for technical documentation [22:09] and it can be built into almost any other format such as HTML, PDF, etc. [22:10] the only real similar alternative I know if in terms of flexibility is TeX and we don't want to go there ;-) [22:10] next [22:11] < jayteeuk> QUESTION: Are the doc team also responsible for this week's session logs? [22:11] no [22:12] the Doc team specially works on the system documentation (what you get installed on your computer) and the wiki on help.ubuntu.com/community [22:12] Ubuntu has a wonderful Scribes team which works on irc transcripts and such [22:12] next [22:13] < bullgard4> QUESTION: It seems to me remarkable that your attention slipped the fact that many manpages are of low or uneven quality. [22:13] ah, this is an interesting question [22:13] we, in general, work on "filling in the gaps" or writing Ubuntu-specific documentation [22:14] because man pages are done by the software authors and are shipped by individual packages it becomes a much more complicated task [22:14] however, it has not slipped our notice that a great many manpages could be improved [22:15] but in terms of priority, we focus more on new users and people who are not familiar with a terminal, and hence probably won't be reading man pages [22:15] but sure, given enough resources we'd love to look at *all* documentation [22:15] next [22:15] < Syntux> QUESTION: Do you guys have a core documentation that fits under a must have with every release? [22:16] hmm [22:16] I guess we do [22:17] we always include information on things like printing, networking, setting up things like graphics cards [22:17] we try to look at at the things that a brand new Ubuntu user would need [22:17] but as this is a volunteer effort we sometimes don't get all we want [22:18] but by this point we've built up a pretty good base of the essential documentation [22:18] so what we do is update the documentation we have for the new release [22:18] then look at things we can add or new features we need to document [22:18] we also have things like a Server Guide and a Switching from Windows guide [22:19] next [22:19] < DoruHush> QUESTION: There is any plan to add to the documentation explanations regarding the use of GUI's and not only command line? (picture will be nice) (humans do not like the Terminal) [22:19] ah [22:20] well we do actually use GUI documentation wherever possible [22:20] however, we don't use a lot of screenshots [22:20] screenshots are very very difficult to keep updated and translated [22:20] Ubuntu documentation is translated into well over 50 languages [22:21] which means screenshots should be correspondingly translated, which is a very difficult task [22:21] so we tend to not use them very much and rather explain in text [22:21] but we do, as a policy, prefer GUI tools over the terminal [22:21] next [22:21] < Syntux> QUESTION: Do you have your own documentation-translation team? any ties with the LoCo team for that purpose? else how does the docs translation works? [22:22] The documentation is translated via Launchpad (Rosetta) just as the rest of Ubuntu is [22:23] we have good ties with the translation teams and we do encourage LoCo teams to maintain localized versions of the wikis [22:23] next [22:23] < bullgard4> QUESTION: It seems to me that for a brand new Ubuntu user an introductory book is esseential as you have provided in the past. How about a Hardy edition? [22:23] I believe the Official Ubuntu Book is being updated [22:23] It is [22:23] there is a 3rd edition on the way [22:24] and because it is released under a free license the Documentation team incorporates it into our documentation [22:24] http://www.mypearsonstore.com/bookstore/product.asp?isbn=0137136684 [22:24] in terms of having a big "User Guide" PDF we've found that users tend to not use them and they are hard to maintain [22:25] instead we've moved to what's called a Topic Based Help system that you seen when you open the Help viewer [22:26] any more questions? perhaps on the wikis? [22:26] *waiting on questions* [22:26] I know it's pretty late on a Friday for most people [22:26] :-) [22:26] I will say that the Documentation team is one of the very best places to get involved with contributing to Ubuntu [22:27] unlike packaging and bug triage which you've probably seen quite a bit of [22:27] documentation doesn't take a lot of technical skill [22:27] having pretty good English skills is about it [22:28] next? [22:28] < bullgard4> QUESTION: What can you do to encourage people to write more Ubuntu Wiki articles than in the past? [22:28] well, there's a couple things there [22:29] first, we can promote it more [22:29] talk about it on Planet Ubuntu, talk to our friends, link more from the forums [22:29] second, we already have a huge amount of documentation on the wikis [22:29] a lot of what we really need is people to expand or clean up existing articles [22:29] documentation is very much a collaborative process [22:30] some people are good about starting pages and getting them organized [22:30] some people are good at expanding and making pages more user-friendly [22:30] some people are good at proofreading and check spelling and grammar [22:30] we need all those people [22:30] next [22:30] < DoruHush> QUESTION: The KDE4 documentation it is included at this time into the ubuntu documentation? Or it is expected the final (stable) release of the Kubuntu KDE4 to do that? [22:31] well, I believe there is KDE4 documentation [22:31] to be honest Richard Johnson, who I'm replacing as he couldn't be here, is the one to ask [22:32] but we at least have the documentation that KDE4 people have written [22:32] next [22:32] *waiting on questions* [22:32] < DoruHush> QUESTION: On the wiki at this time are a lot of pages that are outdated, and are in desperate need of updates (upgrades). How the community can help with that? [22:33] what we need for the wiki is really a "critical mass" of people [22:33] we have people who work on the wiki here and there trying to update and clean up [22:34] but once we get enough people together into a common effort we can really get a lot done [22:34] for people who are interested I would highly recommend joining the ubuntu-doc mailing list [22:34] you can find it on http://lists.ubuntu.com [22:34] the documentation team does have a wiki team [22:34] https://launchpad.net/~ubuntu-wiki [22:35] that's a good place to get started [22:35] if you want to jump in check out https://help.ubuntu.com/community/CategoryCleanup [22:35] which lists pages that need cleaning up [22:36] and https://help.ubuntu.com/community/WikiGuide which helps you know our "standards" [22:36] next [22:36] < bullgard4> QUESTION: Ever thought of an incentive "Best Wiki artcle of the month"? [22:36] that could be a lot of fun [22:37] please send an email about that to the ubuntu-doc list [22:37] I think that could definately be something fun to do [22:37] thanks for the suggestion [22:37] next [22:37] < gscholz> QUESTION: Going back to the translation issue, how is updating managed? Is an old translation lost if the original English text is updated? When I look at my German help browser on the same page I find English paragraphs mixed up with German ones. [22:37] ah [22:37] well, that can happen [22:38] the documentation is frozen before release to allow time for translators to do their work [22:38] but often times translations are not complete [22:38] we don't "throw away" a translation just because it isn't 100% done [22:39] we ship what we have (there is a threshold of around 10% for space considerations) [22:39] next [22:39] < BonesolTeraDyne> QUESTION: Is there a site that would help a newbie learn to write documentation in Docbook format? I mean a decent step-by-step, not something that just explains the process. [22:39] hmm [22:40] I can't think of a really really good one [22:41] one of the best things to do is to just jump in [22:41] you can head over to #ubuntu-doc any time to ask questions [22:41] plus you might want to sign up for the Mentoring program [22:41] there you can get more one-on-one help [22:41] https://wiki.ubuntu.com/DocumentationTeam/Mentoring [22:42] https://help.ubuntu.com/community/DocBook might be some help [22:42] next [22:42] < DoruHush> QUESTION: The wiki pages can be localized (translated) into other languages? [22:42] they certainly can be, but we don't host them on wiki.ubuntu.com or help.ubuntu.com [22:43] what we prefer is to have LoCos maintain a copy of the wikis on their sight [22:43] in this way we hope to point users to the LoCos [22:43] and to their specific language [22:43] and help.ubuntu.com doesn't get full of 50 versions of each page :-) [22:43] next [22:44] *waiting on questions* [22:44] someone linked to this though for docbook: http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/ar01s04.html [22:44] thanks dsas! [22:45] one question we often get is why an Ubuntu Documentation team exists at all [22:45] that we should point people to upstream documentation teams like Gnome or KDE [22:46] what the Ubuntu Doc team does is write documentation that links things together [22:46] or documents places where we've changed things in Ubuntu [22:46] we write documentation for specific task rather than for specific programs [22:47] and now that Hardy has been released [22:47] we've got an effort going to go help out the Gnome Documentation team for a while before we really get into Intrepid's docs [22:47] so we do try to work closely with upstream documentation teams [22:48] any more questions? anything at all? [22:49] I would encourage anybody interested in documentation to join the ubuntu-doc mailng list [22:50] it's a low-key hang out :-) [22:50] and do remember that the documentation team does more than just Ubuntu [22:51] for Hardy the Xubuntu and Server documentors did some really awesome work [22:51] < DoruHush> QUESTION: In the lifetime of one Ubuntu distribution (version) the translations are updated? Or they remain like they were in the day of the release? [22:51] we treat documentation much the same way as anything else in Ubuntu [22:52] we have a freeze about a month or so before release [22:52] to allow for tranlsations and also for us to proofread [22:52] after release people will find "bugs" [22:52] typos, maybe an incorrect command [22:53] and we will fix those if they're important [22:53] we also ship updated translations after release (about once a month or so) [22:53] so people are always encouraged to keep translating :-) [22:53] if you find an error in the system documentation please file a bug [22:54] time for one more question! [22:56] ok, no questions [22:56] alrighty [22:56] thanks so much everyone for participating in another day of openweek! [22:56] thank you all for your questions [22:56] and thanks LaserJock for filling in! [22:56] no problem [22:56] Next sessions start @ 1500UTC tomorrow [22:56] So we'll see you all again tomorrow, thanks! }}}