IntoDocumenting

Ubuntu Open Week - Introduction to the Ubuntu Documentation Project - TBA - Fri, Nov 6, 2009

  • utc

(03:03:57 PM) mdke: I'm here to talk about the Ubuntu Documentation Project
(03:04:15 PM) mdke: It's an excellent way for newcomers to the community to get involved in Ubuntu
(03:04:35 PM) mdke: because it doesn't require substantial technical skills - just the ability to write reasonable English and a willingness to help
(03:05:16 PM) mdke: what I'm going to do today is a whistestop tour through the documentation team, just as an introduction
(03:05:34 PM) mdke: then, we'll run some more detailed sessions for people interested in contributing next week
(03:06:12 PM) mdke: stay tuned here for the details of that, I'll announce them at the end
(03:06:40 PM) mdke: right, an intro to the team
(03:06:45 PM) mdke: The documentation team is completely made up of volunteers. 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
(03:06:57 PM) mdke: We have a mailing list and hang out on irc at #ubuntu-doc
(03:07:15 PM) mdke: There are essentially two types of documentation that the team produces. The ultimate reference page for any information is https://wiki.ubuntu.com/DocumentationTeam
(03:07:31 PM) mdke:    1. System documentation - this is written in a markup language called Docbook XML, and is hosted in our repository.
(03:07:50 PM) mdke: (That's the documentation that you see when you click on System->Help and Support on your Ubuntu system
(03:08:01 PM) mdke: or click the question mark button on the panel)
(03:08:16 PM) mdke:    2. Online documentation - composed of an html version of 1., and a community driven wiki (https://help.ubuntu.com/community)
(03:08:34 PM) mdke: I’ll discuss each in turn. I'm going to start with the community driven wiki first, because that is the easiest place for new contributors to get started with documentation.
(03:08:55 PM) mdke: = Wiki Documentation =
(03:09:03 PM) mdke: The wiki is found at https://help.ubuntu.com/community. As with wikipedia, it is a collaborative resource which is free to anyone to edit.
(03:09:34 PM) mdke: This provides a resource for users to search for help when they come across those unusual problems that baffle us all occasionally
(03:09:46 PM) mdke: The most basic way to contribute is simply to correct errors that you find in any particular document.
(03:10:02 PM) mdke: There are plenty! It's a huge resource, and not all of the pages are perfect by any means
(03:10:16 PM) mdke: This is really easy to do: the first step is to log into the wiki (using your launchpad account)
(03:10:34 PM) mdke: You do this by visiting https://help.ubuntu.com/community/ and then clicking on the "Login to Edit" link in the top right hand corner. Wait a few moments and you are taken to a Launchpad login page. Just click, "Sign In", and you're logged into the wiki.
(03:10:41 PM) mdke: Feel free to try it now!
(03:11:20 PM) mdke: Next, you visit the page you want to edit, say for example https://help.ubuntu.com/community/Installation/SystemRequirements. You then bring up the edit box, by clicking "Show Editing Options" in the bottom right hand corner. That gives you the various options that you have, including to edit the page.
(03:11:53 PM) mdke: The wiki is written in a simple markup language, which allows us to create basic formatting such as section titles and links.
(03:12:18 PM) mdke: Wikipedia has the same, but the markup used is slightly different
(03:12:53 PM) mdke: The wiki markup is very simple. It's easy to get to understand how it works. You can either read the markup of existing pages (by clicking "More Actions" -> "Raw Text" in the edit bar) or you can read through our guides to the wiki.
(03:13:11 PM) mdke: The most important guide to read for anyone working on the wiki is the WikiGuide, found here: https://help.ubuntu.com/community/WikiGuide.
(03:14:19 PM) mdke: The WikiGuide is the basic reference point whenever you want to find out how to do something as a wiki editor. It also gives you guidance about our standard practices
(03:15:01 PM) mdke: I hope that it's easy to understand - but if anything isn't clear feel free to let us know by posting to our mailing list
(03:15:10 PM) mdke: We're always eager to improve our own documentation :)
(03:15:31 PM) mdke: Once you are familiar with the wiki, the next step is to figure out how you can help. Obviously, you can review existing pages that you are interested in or happen to come across, but you may want some guidance about specific tasks.
(03:16:24 PM) mdke: Our basic task list is at https://wiki.ubuntu.com/DocumentationTeam/Wiki/Tasks. The Ubuntu Beginners Team also has a task list for their "Wiki Focus Group", which works closely with the Documentation Team, here: https://help.ubuntu.com/community/Beginners/Development
(03:17:06 PM) mdke: A great way to find pages that need work is by using the tag system. We have a number of different tags that we apply to pages that need different types of attention.
(03:17:40 PM) mdke: You can read about the different tags and how to use them here: https://help.ubuntu.com/community/Tag.
(03:18:12 PM) mdke: The different tags are: Unsupported Version, Content cleanup required, Style cleanup required, Needs Expansion, Page too long, Candidate for moving, Candidate for deletion, Duplicate article.
(03:18:48 PM) mdke: Great tags for finding pages that need work are the first five of those. These are pages that are outdated, unclear, too short, or too long.
(03:19:09 PM) mdke: You can find the list of pages with a particular tag by visiting https://help.ubuntu.com/community/Tag, going to the relevant tag, and clicking on "List of pages with this tag".
(03:20:18 PM) mdke: Then, you just pick a page, and start working on improving it! Feel free to get in touch with the team on the mailing list to let them know the work that you are doing on any particular page, and to seek advice if you need it.
(03:20:49 PM) mdke: If you come across a page that you think needs improving, and it doesn't have a tag, you can add one using the instructions on the "Tag" page
(03:21:03 PM) mdke: Right now we have a *lot* of tagged pages, so there is plenty of work to do!
(03:21:44 PM) mdke: Ok, that in a nutshell is the community help wiki. I'd encourage anyone interested in helping out with documentation to check it out, and in particular to start with this page: https://help.ubuntu.com/community/WikiGuide
(03:22:32 PM) mdke: This might be a good moment to take a break for questions
(03:22:33 PM) mdke: If anyone has any questions about the wiki, feel free to ask them now in #ubuntu-classroom-chat
(03:24:12 PM) mdke: 20:24:01 < saji> Hey What is the difference between https://help.ubuntu.com/community and wiki.ubuntu.com?
(03:24:16 PM) mdke: excellent question!
(03:24:38 PM) mdke: Both of these sites are wikis, so they are collaborative resources which are free for anyone to edit
(03:24:53 PM) mdke: the key distinction is that https://help.ubuntu.com/community is only for documentation
(03:25:10 PM) mdke: and wiki.ubuntu.com is only for team organisation and planning
(03:25:26 PM) mdke: so you can see help.ubuntu.com as a site for users, and wiki.ubuntu.com as a site for contributors to Ubuntu
(03:26:29 PM) akgraner: <dhillon-v10> QUESTION: mdke, now that you are here, me and Phil were talking about this: how do we go about getting a survey of people
(03:26:41 PM) mdke: just a followup on the previous question
(03:26:54 PM) mdke: saji has pointed out that there are some help documents on wiki.ubuntu.com
(03:27:09 PM) mdke: The simple answer is that these are there by mistake, and should be moved
(03:27:35 PM) mdke: If you see a document for users on wiki.ubuntu.com, it can be reported by adding the word "CategoryDocumentation" at the bottom of the page
(03:27:42 PM) mdke: that will add it to the list to be moved
(03:28:12 PM) mdke: ok, to address dhillon-v10's question
(03:28:28 PM) mdke: at the moment we don't have much feedback from users about how helpful our website or help pages are
(03:29:13 PM) mdke: I personally think that there should be a way for a user to report easily possible errors or complaints about wiki pages, without having to file a bug report, just by clicking on a button on the page
(03:29:20 PM) mdke: it could even be a short survey embedded into the page
(03:29:43 PM) mdke: but we haven't discussed this as a team properly, and I'd encourage dhillon-v10 to post to the mailing list about it for a full discussion and brainstorming session
(03:30:43 PM) mdke: QUESTION: 20:30:21 < saji> mdke, where will the pages relating to troubleshooting come under?
(03:31:15 PM) mdke: A page which involves troubleshooting a piece of software to help a user will generally be for help.ubuntu.com
(03:32:33 PM) mdke: sometimes there are borderline cases, we don't always get the distinction right, but we try!
(03:33:44 PM) mdke: Right, I'm going to move on to discussing the second type of documentation that we have now
(03:33:49 PM) mdke: = System Documentation =
(03:34:04 PM) mdke: The System documentation is the documentation that is included by default with every Ubuntu system
(03:34:26 PM) mdke: It appears in the menu at System->Help and Support, or by clicking on the blue question mark in the top panel
(03:34:58 PM) mdke: Because this documentation is included with every Ubuntu system, we run a stricter system of quality control
(03:35:05 PM) mdke: it's not open to everyone to edit like the wiki is
(03:35:20 PM) mdke: But, it's still easy to contribute!
(03:35:40 PM) mdke: As usual, the starting place to learn how to contribute is our team wiki page, at https://wiki.ubuntu.com/DocumentationTeam
(03:35:47 PM) mdke: In particular: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation
(03:36:16 PM) mdke: To prove that it's easy to learn how to contribute to system documentation, take myself as an example
(03:36:51 PM) mdke: I don't have any technical computing training, I'm not a computer scientist. However, I got interested in ubuntu documentation, and found that I'd pretty quickly learned the ropes to make basic contributions
(03:37:23 PM) mdke: Gradually, you get more experienced, and eventually you are completely comfortable contributing, and may be granted full access to edit the documentation
(03:37:48 PM) mdke: So let's take a closer look at how the system documentation works
(03:38:12 PM) mdke: Again, it's written in a markup language. But the markup is more complicated. It's called Docbook XML
(03:38:27 PM) mdke: It's a markup language quite similar to HTML, which webpages are written in, so some of you may be familiar with that
(03:39:12 PM) mdke: As before, the best way to get to know it is to read some existing documents and to read our guides
(03:39:33 PM) mdke: Our guides on Docbook XML start here: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Editing
(03:39:52 PM) mdke: As for reading some existing documents, first we need to download the repository of the documents
(03:40:22 PM) mdke: The documents are stored in a version control repository which anyone can download. the version control system used is BZR
(03:40:36 PM) mdke: Most of the Ubuntu community uses BZR to store its code
(03:41:04 PM) mdke: bzr is pretty easy to learn
(03:41:23 PM) mdke: I don't have time to go into it in too much detail in the time we have, unfortunately
(03:41:36 PM) mdke: Essentially there are a few commands which we use to do just about everything we need
(03:41:52 PM) mdke: "bzr branch" is the command to download the documents.
(03:42:13 PM) mdke: A detailed guide to getting the documents and using bzr can be found here: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository
(03:42:47 PM) mdke: One of the key things to notice is that we have quite a lot of different bzr "branches" that can be downloaded
(03:42:50 PM) mdke: it's important to get the right one
(03:43:06 PM) mdke: The list of all of our branches is here: https://code.launchpad.net/ubuntu-doc-project
(03:43:26 PM) mdke: The main ones for ubuntu-docs, kubuntu-docs, xubuntu-docs and edubuntu-docs have a star by them
(03:43:45 PM) mdke: so to get the ubuntu-docs branch, you would run "bzr branch lp:ubuntu-docs"
(03:44:08 PM) mdke: If you run into any problems having read the guide at https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository, feel free to ask the team for help
(03:45:06 PM) mdke: Again, finding tasks can be one of the thing that newcomers find difficult
(03:45:22 PM) mdke: We keep a list of tasks here: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks
(03:45:39 PM) mdke: the first thing you can do is simply to read the system documentation and point out errors (mistakes, typos, etc)
(03:45:53 PM) mdke: You can point them out by filing bug reports in Launchpad, just as you do with any Ubuntu project
(03:46:13 PM) mdke: Alternatively, you can try and submit a fix for them yourself
(03:46:37 PM) mdke: We have a "quick guide" to doing that - our playbook - https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation?action=AttachFile&do=view&target=BugsPlaybook.pdf
(03:46:53 PM) mdke: That explains how to fix a bug in a few quick and easy steps
(03:47:24 PM) mdke: Once you are familiar with our processes, you can find some more chunky tasks by visiting the https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks page
(03:47:40 PM) mdke: That has links to existing bug reports for our projects, and suggestions for new documents
(03:48:04 PM) mdke: If you aren't comfortable with our markup yet, you can submit material as plain text, and we will convert it into Docbook XML - any contribution is valued
(03:48:48 PM) mdke: That is a (very fast) overview of System Documentation - I know that there will be plenty of things to develop further, and that's part of the point in having some further sessions next week
(03:49:01 PM) mdke: The sessions are going to be as follows:
(03:49:03 PM) mdke: Good Preparation when Writing Documentation - AugustinaBlair
(03:49:30 PM) mdke: Augustina is a new contributor to the team who wrote the help document for USB Startup Disk Creator
(03:50:01 PM) mdke: She did a great job with that and the secret was planning it very well - so she's going to share some thoughts on planning documentation with us
(03:50:07 PM) mdke: The second session is:
(03:50:15 PM) mdke: Project Mallard - Writing Documentation in XML - PhilBull
(03:50:38 PM) mdke: Phil is a longterm contributor to the team, and he will explain in much more detail how to understand the XML markup
(03:51:00 PM) mdke: He'll introduce a different type of XML markup which is being developed at the moment by the Gnome documentation team - Project Mallard
(03:51:13 PM) mdke: the sessions will be run on:
(03:51:19 PM) mdke: 11 November 2009 at 5pm UTC - in #ubuntu-doc
(03:51:33 PM) mdke: If there is a bit of demand, perhaps we can persuade Augustina and Phil to run the sessions again in the future :)
(03:51:55 PM) mdke: Before taking a couple of questions, I'd just like to mention translation as a great way of contributing to Ubuntu Documentation
(03:52:11 PM) mdke: Our documentation is translated into tens and tens of languages by the faithful ubuntu translation teams
(03:52:18 PM) mdke: they do an awesome job, but can always do with help!
(03:52:39 PM) mdke: Have a look at https://wiki.ubuntu.com/DocumentationTeam/Translation if you are interested in translating documentation
(03:53:34 PM) mdke: ok, time for a couple of questions
(03:53:44 PM) mdke: 20:35:57 < airurando> QUESTION: What, if any, are the collaborative links between Ubuntu Documentation and Ubuntu Learning?
(03:54:45 PM) mdke: airurando: At the moment, I'm not too familiar with what the ubuntu Learning project is doing in terms of user teaching. I know that they have developed a project in that area, and we have discussed collaboration at length, but it's still in early stages
(03:55:01 PM) mdke: I haven't been in touch with the learning team recently about this so I am a little out of touch
(03:55:20 PM) mdke: Sorry that I can't answer your question more fully but I'd be happy to followup by email with the learning team about collaborating
(03:55:39 PM) mdke: 20:38:24 < duanedesign> QUESTION: Are there any tools you recommend for working with DocBook XML, like XML Mind?
(03:55:46 PM) mode (+v kenvandine ) by akgraner
(03:56:10 PM) mdke: I have personally tried bluefish, and it was quite good
(03:56:30 PM) mdke: but I didn't try it very extensively, because I found it easy to use a simple text editor for working with docbook XML
(03:56:57 PM) mdke: For example gedit (the default Gnome text editor) is quite good because it hilights the relevant tags that are used
(03:57:14 PM) mdke: Again, I know that's not a great answer :) Other Documentation Team members might have better suggestions
(03:57:20 PM) mdke: Feel free to post to the mailing list about that!
(03:57:40 PM) mdke: 20:49:06 < saji> Question:How can plaintext contributions be made?
(03:57:58 PM) mdke: Plain text contributions can be attached or pasted into bug reports, or sent to the mailing list
(03:58:12 PM) mdke: We probably prefer bug reports, as they can't get lost
(03:58:19 PM) mdke: But either is fine
(03:59:08 PM) mdke: I think we're just about finished on timing, so I'll call a close and thank everyone for their attention
(03:59:24 PM) mdke: Thanks and look forward to seeing you on the ubuntu-doc mailing list and #ubuntu-doc

MeetingLogs/openweekKarmic/IntoDocumenting (last edited 2009-11-06 21:10:04 by pool-68-238-91-2)