Ubuntu Wiki

Ubuntu Open Week - Ubuntu Documentation Project - Sat, Dec 2, 2006

see also Wednesday Session.

07:05   LaserJock       I'm here to do the Doc Team presentation
07:07   LaserJock       Matthew East is not able to make the doc team session so I'm filling in
07:07   LaserJock       Welcome everybody!
07:08   LaserJock       My name is Jordan Mantha
07:08   LaserJock       and I'm a member of the doc team
07:08   LaserJock       so lets get started with what exactly the doc team is
07:09   LaserJock       the Ubuntu Documentation Team is composed of people from Ubuntu, Kubuntu, Xubuntu, and Edubuntu
07:09   LaserJock       who all share a goal of creating the best documentation for Ubuntu (as a whole) that we can
07:10   LaserJock       it is *entirely* community run (there is nobody paid to work on the Doc Team)
07:11   LaserJock       The core team is https://launchpad.net/people/ubuntu-doc but many others contribute to documentation all the time. To find out how to communicate with us, see https://wiki.ubuntu.com/DocumentationTeam/Contact
07:11   LaserJock       There are essentially two types of documentation that the team produces. The ultimate reference page for any information is https://wiki.ubuntu.com/DocumentationTeam
07:11   LaserJock       1. System documentation - this is written in a markup language called Docbook XML, and is hosted in our repository.
07:12   LaserJock       2. Online documentation - composed of an html version of (1), and a community driven wiki (https://help.ubuntu.com/community)
07:12   nixternal       NOTE: System Documentation is also installed on your system (read Help)
07:13   LaserJock       yes, the System Documentation is what we ship on the CD
07:13   LaserJock       and is found in the help systems
07:13   LaserJock       right now it's composed of a series of guides
07:13   LaserJock       we have the Desktop Guide
07:14   LaserJock       Server Guide
07:14   LaserJock       Packaging Guide
07:14   LaserJock       and then you also have things like "About Ubuntu" and Release Notes
07:15   LaserJock       OK, so how does one contribute to the system documentation?
07:15   LaserJock       Diving in and trying things out is the best way to begin getting involved.
07:15   LaserJock       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!
07:16   LaserJock       https://wiki.ubuntu.com/DocumentationTeam/Projects shows a list of projects
07:17   LaserJock       https://wiki.ubuntu.com/DocumentationTeam/Repository will show you how to get the Subversion repository
07:17   LaserJock       and get you started with editing

[LKRaider] how does the doc team work with internationalization teams?

• well, I'll talk more about that later, but the basics are we create templates for the docs that are put on Rosetta for the translation teams to work on and then we gather the translations and put then in the documentation packages. we have been very careful to "freeze" our docs early enough that translators have a decent amount of time to translate

07:19   LaserJock       ok, so some easy areas to contribute with system documentation:
07:20   LaserJock       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 https://launchpad.net/products/ubuntu-doc/+bugs and 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!)
07:20   LaserJock       Some of the key tasks for the system documentation are:
07:21   LaserJock       1. Improving the navigability and readability of the help (https://wiki.ubuntu.com/TopicBasedHelp).
07:21   LaserJock       2. Incorporating material from the Official Ubuntu Book into appropriate sections in the system documentation, amending the style accordingly.
07:21   LaserJock       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).
07:21   LaserJock       4. Updating existing information which is no longer valid due to inclusion of new features in Feisty.
07:22   LaserJock       OK, I'd like to open it up for questions about system documentation

<nixternal> can you explain the Topic Based Help

• heh, loaded questions, I love it! traditionally we have shipped discrete "guides" where each guide has a specific target audience and set of topics more like a book, essentially, but it makes it hard for users to get what they want. they aren't interested in reading a book as much as they are interested in learning about a specific topic so we are working on rearranging the contents of our guide to reflect that. in fact it should look a quite a bit like the help wiki main page http://help.ubuntu.com/community/

[sid] Would the non-free software in Ubuntu fall under system documentation? or no? like binary blob/binary codec wrapper stuff

• depends on what you mean

  Are there any templates for explaining to users the pitfalls of non-free software?(ie binary blobs/binary codec wrappers etc) Explaining to them how their data is locked into a format that helps the developers of the format make more money? Or what direction will the non-free software aspect of Ubuntu go?

  • we do document non-free codecs, etc.

  [sid] Well I'm talking about the education stuff for feisty Is there a design for that yet? Or is it too early?

  • we don't quite have as much on education but I'm sure that will come along

[LKRaider] any plans of introducing more context sensitive help on the system?

• the answer to that is basically, we'd like to but we are also bound by the help systems provided by upstreams. so right now we'd like to do more, but Gnome and KDE haven't developed their topic based help systems yet

  [LKRaider] ... I would like to see a help tightly integrated into the system tho :)

  • yes, we would too. right now there are technical reasons why that isn't so easy. one is licensing. one is a system to actual integrate, the Gnome and KDE help systems aren't so great for that

[sid] Do you have an opinion on the direction the non-free documentation should go? Will the text be worded so the users want to not use non-free software at all? Meaning they won't want to save their home movies in .wmv, or more strong would be they don't accept .doc files in their email and only accept odf? In your opinion how strong should the documentation be in favor of open standards and free/libre software? Or should it just make them aware of the non-free software, just so they know it exists?

• === nixternal despises documenting non-free and will refuse to do so ok, well some of that will certainly depend on what the Ubuntu Technical Board does with some of the issues we face in Feisty, but to be honest, our job is to document the Ubuntu project and not so much to make policy decisions. we do have to decide how we handle certain things. for instance we have chosen to try to use GUI tool wherever possible in our documentation. I'm almost certain we will at least show the user the choices and explain why certain things are non-free. we already do that a fair amount with the restricted codecs. so I don't see that changing but to be honest that's really not a big deal. the vast majority of our work has nothing to do with free vs non-free

[nixternal] a majority of our System Documentation documents the standard or default applications that are installed on the CD. Our wiki on the other hand is community created

[LKRaider] About the Ubuntu book, was it done by the doc team? Are there plans for releasing other books? (like a server book)

• The Ubuntu Book was not done by the doc team. a few of hte members of the doc team were among the authors but the publisher sought them out, but the Official Ubuntu Book was released under a license that will allow us to integrate it into the doc team material. which is very rare

[Rondom] The wiki is rather unstructured. I don't know where to start. Are there any plans on a clean structure (categories like hardware->soundcards->xyz-soundcard-article)?

• Ok, well rather then answering your question directly, let me now talk about the wiki docs I might answer your question a little bit there

07:38   LaserJock       OK, so the wiki help is housed at help.ubuntu.com/community
07:38   LaserJock       this again is a community run effort
07:38   LaserJock       this wiki is open to everybody
07:38   LaserJock       so it is a very easy way to start getting involved with documentation
07:39   LaserJock       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.
07:39   LaserJock       Above anything else, read the wiki guide: https://help.ubuntu.com/community/WikiGuide.
07:39   LaserJock       One way of becoming familiar with the material and how we work is to begin reading it and checking it for accuracy.
07:40   LaserJock       A number of more substantial "wiki-tasks" (as well as a list of pages that need serious attention) are listed on https://help.ubuntu.com/community/WikiToDo.
07:40   LaserJock       Some of the key tasks are:
07:40   LaserJock       1. 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!
07:40   LaserJock       2. Doing quality assurance to ensure users are given reliable information and can quickly identify how reliable a page is.
07:41   LaserJock       3. 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)
07:41   LaserJock       4. Clarify the license of material on the wiki by convincing the Community Council to approve the year-old specification (https://wiki.ubuntu.com/WikiLicensing).
07:41   LaserJock       A long-term goal 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, and (the other side of the coin)
07:41   LaserJock       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.
07:42   LaserJock       I'll let you read for a while
07:42   LaserJock       and then feel free to ask any wiki questions

[Rondom] I read, maybe not enough, I'm actually looking for some wiki-team-mailing list for discussing things or some results of discussions that were already made

• ok, well the wiki team uses the doc team mailing list. ubuntu-doc on lists.ubuntu.com. so feel free to introduce yourself and ask questions. #ubuntu-doc is also a great place for quick questions. if you are editing a wiki page and you're a little nervous about it you can always email the doc team and ask for a review

[ LKRaider] about porting stuff from the forums, do you have a team that does that, or just rely on users bringing the doc-work available there?

• there is a team composed of forum and doc team people. right now it's not very active as we are having licensing issues. one of the more complicated issues in documentation is licensing. we are working towards have those worked out

[sid] Can't you just setup the forum so they agree to submit their docs under the GFDL? And the wiki and whatever else.

• well, they are licensed under CC-SA I believe and the wiki doesn't currently have a license but it is proposed to be more of a Public Domain style

[sid] So can't you setup the wiki and forum and whatever else, so they can't submit unless they agree to put their works in the public domain?

• well, the issue is you have potentially thousands of authors. so right now what you can do is if you find a howto on the forums you want to put on the wiki. you need to ask the author for permission to put it on the wiki. if we had compatible licenses we could do some "mass" moving of documentation

  [sid] Although I prefer CC-SA or GFDL as opposed to the public domain. Something about microsoft turning my documentation into non-freeness and then selling it makes me want to vomit. Wikipedia does it the best imho, almost all of their work is under GFDL. The idea should be to promot more documentation(GFDL), just like promoting more free software(GPL). imho.

  • well, GFDL is often considered non-free so sometimes that's an issue

[lumpki] How can users identify how reliable a wiki page is?

• well, right now it's pretty tough but that is an area we are keen on improving. we'd sure welcome and suggestions or help. more info check out https://wiki.ubuntu.com/HelpWikiQualityAssurance [nixternal] it is tough, but if at all possible, people on the wiki team go through and test it. and then usually clean it up and post it for good..it would be nice to have a comments section on the bottom of each help page for people to say yes it worked or no im dead

  [lumpki] or maybe a voting system something like a "Did this page work for you?" kind of thing

[LKRaider] continuing on lumpki's question, the brazilian-doc-team have made their wiki pages signed by "maintainers", where users can turn to ask questions on the topic of the page to request help. What do you think of this idea?

I don't think it would work to well on our scale

07:57   LaserJock       ok, let me just wrap up here with a couple translation items
07:57   LaserJock       If you are a translator, and are interested in helping out translating the Ubuntu documentation into your language, all you need to know is how to use the Rosetta translation system
07:58   LaserJock       http://launchpad.net/rosetta
07:58   LaserJock       You can find out how to use that on the Rosetta wiki page - https://wiki.ubuntu.com/Rosetta.
07:58   LaserJock       Once you have learnt all of this, the docteam documents can be found in several places:
07:58   LaserJock       https://launchpad.net/distros/ubuntu/dapper/+source/ubuntu-docs
07:59   LaserJock       https://launchpad.net/distros/ubuntu/dapper/+source/kubuntu-docs
07:59   LaserJock       https://launchpad.net/distros/ubuntu/dapper/+source/xubuntu-docs
07:59   LaserJock       OK, that's it for me
07:59   LaserJock       and we're out of time
08:00   LaserJock       so I'd just encourage everybody to take a look at the Documentation Team
08:00   LaserJock       head over to #ubuntu-doc if you have more questions
08:01   LaserJock       Thanks Everybody!!