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] <jcastro> Unfortunately Richard Johnson has a power outage, so Jordan Mantha, aka LaserJock will be filling in

[21:56] <jcastro> In about 5 minutes. :D

[22:00] <jcastro> ok LaserJock, take it away!

[22:00] <LaserJock> ok people, time to get excited!

[22:00] <LaserJock> My name is Jordan Mantha and I'm a volunteer developer for Ubuntu

[22:01] <LaserJock> 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] <LaserJock> The Doc Team is an all-volunteer army of people with a variety of 
technical abilities and backgrounds

[22:02] <LaserJock> with the goal of providing first-class system documentation for Ubuntu, 
Kubuntu, Xubuntu, and Edubuntu

[22:02] <LaserJock> as well as trying to calm the chaos that is the Ubuntu wikies

[22:03] <LaserJock> 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] <LaserJock> the system documentation is written in docbook for people who care :-)

[22:04] <LaserJock> but we also have a DocuMENTORs program for people who want to get 
mentored into the team

[22:04] <LaserJock> and they can join a Documentation Students team

[22:05] <LaserJock> https://launchpad.net/~ubuntu-doc/+members gives an overview of the teams

[22:05] <LaserJock> https://wiki.ubuntu.com/DocumentationTeam is a general intro to what we 
work on

[22:05] <LaserJock> and https://wiki.ubuntu.com/DocumentationTeam/Mentoring talks about the 
mentoring program

[22:06] <LaserJock> are there any questions at this point?

[22:07] <LaserJock>  QUESTION: Why should people care about docbook?

[22:08] <LaserJock> well, docbook has lots of advantages, and some disadvantages

[22:08] <LaserJock> docbook is nice because it has a fairly simple, XML, syntax

[22:08] <LaserJock> if you know any HTML you can pick it up easily

[22:09] <LaserJock> it's also built specifically for technical documentation

[22:09] <LaserJock> and it can be built into almost any other format such as HTML, PDF, etc.

[22:10] <LaserJock> the only real similar alternative I know if in terms of flexibility is 
TeX and we don't want to go there ;-)

[22:10] <LaserJock> next

[22:11] <jcastro> < jayteeuk> QUESTION: Are the doc team also responsible for this week's 
session logs?

[22:11] <LaserJock> no

[22:12] <LaserJock> 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] <LaserJock> Ubuntu has a wonderful Scribes team which works on irc transcripts and 
such

[22:12] <LaserJock> next

[22:13] <jcastro> < bullgard4> QUESTION: It seems to me remarkable that your attention 
slipped the fact that many manpages are of low  or uneven  quality.

[22:13] <LaserJock> ah, this is an interesting question

[22:13] <LaserJock> we, in general, work on "filling in the gaps" or writing Ubuntu-specific 
documentation

[22:14] <LaserJock> because man pages are done by the software authors and are shipped by 
individual packages it becomes a much more complicated task

[22:14] <LaserJock> however, it has not slipped our notice that a great many manpages could 
be improved

[22:15] <LaserJock> 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] <LaserJock> but sure, given enough resources we'd love to look at *all* documentation

[22:15] <LaserJock> next

[22:15] <jcastro> < Syntux> QUESTION: Do you guys have a core documentation that fits under a 
must have with every release?

[22:16] <LaserJock> hmm

[22:16] <LaserJock> I guess we do

[22:17] <LaserJock> we always include information on things like printing, networking, 
setting up things like graphics cards

[22:17] <LaserJock> we try to look at at the things that a brand new Ubuntu user would need

[22:17] <LaserJock> but as this is a volunteer effort we sometimes don't get all we want

[22:18] <LaserJock> but by this point we've built up a pretty good base of the essential 
documentation

[22:18] <LaserJock> so what we do is update the documentation we have for the new release

[22:18] <LaserJock> then look at things we can add or new features we need to document

[22:18] <LaserJock> we also have things like a Server Guide and a Switching from Windows 
guide

[22:19] <LaserJock> next

[22:19] <jcastro> < 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] <LaserJock> ah

[22:20] <LaserJock> well we do actually use GUI documentation wherever possible

[22:20] <LaserJock> however, we don't use a lot of screenshots

[22:20] <LaserJock> screenshots are very very difficult to keep updated and translated

[22:20] <LaserJock> Ubuntu documentation is translated into well over 50 languages

[22:21] <LaserJock> which means screenshots should be correspondingly translated, which is a 
very difficult task

[22:21] <LaserJock> so we tend to not use them very much and rather explain in text

[22:21] <LaserJock> but we do, as a policy, prefer GUI tools over the terminal

[22:21] <LaserJock> next

[22:21] <jcastro> < 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] <LaserJock> The documentation is translated via Launchpad (Rosetta) just as the rest 
of Ubuntu is

[22:23] <LaserJock> we have good ties with the translation teams and we do encourage LoCo 
teams to maintain localized versions of the wikis

[22:23] <LaserJock> next

[22:23] <jcastro> < 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] <LaserJock> I believe the Official Ubuntu Book is being updated

[22:23] <jcastro> It is

[22:23] <jcastro> there is a 3rd edition on the way

[22:24] <LaserJock> and because it is released under a free license the Documentation team 
incorporates it into our documentation

[22:24] <jcastro> http://www.mypearsonstore.com/bookstore/product.asp?isbn=0137136684

[22:24] <LaserJock> 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] <LaserJock> instead we've moved to what's called a Topic Based Help system that you 
seen when you open the Help viewer

[22:26] <LaserJock> any more questions? perhaps on the wikis?

[22:26] <jcastro> *waiting on questions*

[22:26] <LaserJock> I know it's pretty late on a Friday for most people

[22:26] <LaserJock> :-)

[22:26] <LaserJock> I will say that the Documentation team is one of the very best places to 
get involved with contributing to Ubuntu

[22:27] <LaserJock> unlike packaging and bug triage which you've probably seen quite a bit of

[22:27] <LaserJock> documentation doesn't take a lot of technical skill

[22:27] <LaserJock> having pretty good English skills is about it

[22:28] <LaserJock> next?

[22:28] <jcastro>  < bullgard4> QUESTION: What can you do to encourage people to write more 
Ubuntu Wiki articles than in the past?

[22:28] <LaserJock> well, there's a couple things there

[22:29] <LaserJock> first, we can promote it more

[22:29] <LaserJock> talk about it on Planet Ubuntu, talk to our friends, link more from the 
forums

[22:29] <LaserJock> second, we already have a huge amount of documentation on the wikis

[22:29] <LaserJock> a lot of what we really need is people to expand or clean up existing 
articles

[22:29] <LaserJock> documentation is very much a collaborative process

[22:30] <LaserJock> some people are good about starting pages and getting them organized

[22:30] <LaserJock> some people are good at expanding and making pages more user-friendly

[22:30] <LaserJock> some people are good at proofreading and check spelling and grammar

[22:30] <LaserJock> we need all those people

[22:30] <LaserJock> next

[22:30] <jcastro> < 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] <LaserJock> well, I believe there is KDE4 documentation

[22:31] <LaserJock> to be honest Richard Johnson, who I'm replacing as he couldn't be here, 
is the one to ask

[22:32] <LaserJock> but we at least have the documentation that KDE4 people have written

[22:32] <LaserJock> next

[22:32] <jcastro> *waiting on questions*

[22:32] <jcastro> < 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] <LaserJock> what we need for the wiki is really a "critical mass" of people

[22:33] <LaserJock> we have people who work on the wiki here and there trying to update and 
clean up

[22:34] <LaserJock> but once we get enough people together into a common effort we can really 
get a lot done

[22:34] <LaserJock> for people who are interested I would highly recommend joining the 
ubuntu-doc mailing list

[22:34] <LaserJock> you can find it on http://lists.ubuntu.com

[22:34] <LaserJock> the documentation team does have a wiki team

[22:34] <LaserJock> https://launchpad.net/~ubuntu-wiki

[22:35] <LaserJock> that's a good place to get started

[22:35] <LaserJock> if you want to jump in check out 
https://help.ubuntu.com/community/CategoryCleanup

[22:35] <LaserJock> which lists pages that need cleaning up

[22:36] <LaserJock> and https://help.ubuntu.com/community/WikiGuide which helps you know our 
"standards"

[22:36] <LaserJock> next

[22:36] <jcastro> < bullgard4> QUESTION: Ever thought of an incentive "Best Wiki artcle of 
the month"?

[22:36] <LaserJock> that could be a lot of fun

[22:37] <LaserJock> please send an email about that to the ubuntu-doc list

[22:37] <LaserJock> I think that could definately be something fun to do

[22:37] <LaserJock> thanks for the suggestion

[22:37] <LaserJock> next

[22:37] <jcastro> < 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] <LaserJock> ah

[22:37] <LaserJock> well, that can happen

[22:38] <LaserJock> the documentation is frozen before release to allow time for translators 
to do their work

[22:38] <LaserJock> but often times translations are not complete

[22:38] <LaserJock> we don't "throw away" a translation just because it isn't 100% done

[22:39] <LaserJock> we ship what we have (there is a threshold of around 10% for space 
considerations)

[22:39] <LaserJock> next

[22:39] <jcastro> < 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] <LaserJock> hmm

[22:40] <LaserJock> I can't think of a really really good one

[22:41] <LaserJock> one of the best things to do is to just jump in

[22:41] <LaserJock> you can head over to #ubuntu-doc any time to ask questions

[22:41] <LaserJock> plus you might want to sign up for the Mentoring program

[22:41] <LaserJock> there you can get more one-on-one help

[22:41] <LaserJock> https://wiki.ubuntu.com/DocumentationTeam/Mentoring

[22:42] <LaserJock> https://help.ubuntu.com/community/DocBook might be some help

[22:42] <LaserJock> next

[22:42] <jcastro> < DoruHush> QUESTION: The wiki pages can be localized (translated) into 
other languages?

[22:42] <LaserJock> they certainly can be, but we don't host them on wiki.ubuntu.com or 
help.ubuntu.com

[22:43] <LaserJock> what we prefer is to have LoCos maintain a copy of the wikis on their 
sight

[22:43] <LaserJock> in this way we hope to point users to the LoCos

[22:43] <LaserJock> and to their specific language

[22:43] <LaserJock> and help.ubuntu.com doesn't get full of 50 versions of each page :-)

[22:43] <LaserJock> next

[22:44] <jcastro> *waiting on questions*

[22:44] <jcastro> someone linked to this though for docbook: 
http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/ar01s04.html

[22:44] <jcastro> thanks dsas!

[22:45] <LaserJock> one question we often get is why an Ubuntu Documentation team exists at 
all

[22:45] <LaserJock> that we should point people to upstream documentation teams like Gnome or 
KDE

[22:46] <LaserJock> what the Ubuntu Doc team does is write documentation that links things 
together

[22:46] <LaserJock> or documents places where we've changed things in Ubuntu

[22:46] <LaserJock> we write documentation for specific task rather than for specific 
programs

[22:47] <LaserJock> and now that Hardy has been released

[22:47] <LaserJock> 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] <LaserJock> so we do try to work closely with upstream documentation teams

[22:48] <LaserJock> any more questions? anything at all?

[22:49] <LaserJock> I would encourage anybody interested in documentation to join the 
ubuntu-doc mailng list

[22:50] <LaserJock> it's a low-key hang out :-)

[22:50] <LaserJock> and do remember that the documentation team does more than just Ubuntu

[22:51] <LaserJock> for Hardy the Xubuntu  and Server documentors did some really awesome 
work

[22:51] <jcastro> < 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] <LaserJock> we treat documentation much the same way as anything else in Ubuntu

[22:52] <LaserJock> we have a freeze about a month or so before release

[22:52] <LaserJock> to allow for tranlsations and also for us to proofread

[22:52] <LaserJock> after release people will find "bugs"

[22:52] <LaserJock> typos, maybe an incorrect command

[22:53] <LaserJock> and we will fix those if they're important

[22:53] <LaserJock> we also ship updated translations after release (about once a month or 
so)

[22:53] <LaserJock> so people are always encouraged to keep translating :-)

[22:53] <LaserJock> if you find an error in the system documentation please file a bug

[22:54] <jcastro> time for one more question!

[22:56] <jcastro> ok, no questions

[22:56] <LaserJock> alrighty

[22:56] <jcastro> thanks so much everyone for participating in another day of openweek!

[22:56] <LaserJock> thank you all for your questions

[22:56] <jcastro> and thanks LaserJock for filling in!

[22:56] <LaserJock> no problem

[22:56] <jcastro> Next sessions start @ 1500UTC tomorrow

[22:56] <jcastro> So we'll see you all again tomorrow, thanks!