Ubuntu Wiki

   1 [17:32] <jbicha> Hi, I'm Jeremy Bicha and I'm a volunteer member of Ubuntu's Documentation and Desktop teams.
   2 [17:32] <jbicha> I joined the Documentation Team a year ago as Ubuntu badly needed help with integrating the new GNOME User Guide
   3 [17:32] <jbicha> with Ubuntu documentation where we obviously use Unity by default instead of GNOME Shell.
   4 [17:33] <jbicha> Today, I'd like to show you how you can get started with contributing to Ubuntu's documentation.
   5 [17:34] <jbicha> I really like that you don't need to really be a coder to write good documentation; you just need good English writing skills and attention to detail.
   6 [17:34] <jbicha> If you visit our team's wiki page, you can see that there are several different areas we work on.
   7 [17:34] <jbicha> https://wiki.ubuntu.com/DocumentationTeam
   8 [17:34] <jbicha> There is the help wiki which anyone can edit and all you need is a Ubuntu One/Launchpad account.
   9 [17:34] <jbicha> https://help.ubuntu.com/community
  10 [17:35] <jbicha> One thing that's confused me in the past about Ubuntu's wiki is that there are actually two of them!
  11 [17:35] <jbicha> help.ubuntu.com is a reference for Ubuntu-related "how-to's, tips, tricks, and hacks" whereas wiki.ubuntu.com is a resource for contributing to Ubuntu so it has pages for all the different Ubuntu teams you can join.
  12 [17:35] <jbicha> So if you want to contribute help guides, you can do that at help.ubuntu.com/community.
  13 [17:35] <jbicha> Secondly, the Ubuntu Docs Team is responsible for the help that's shipped inside Ubuntu and the other Ubuntu flavors (Kubuntu, Xubuntu, etc.)
  14 [17:36] <jbicha> You can see this system help if you type help into the dash in Unity.
  15 [17:36] <jbicha> This help is also mirrored to https://help.ubuntu.com/11.10/ubuntu-help/
  16 [17:36] <jbicha> There's several different ways you can help out with the system documentation.
  17 [17:36] <jbicha> You can read the help and file bugs if you see typos.
  18 [17:37] <jbicha> https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs/
  19 [17:37] <jbicha> Since this is Developer Week, I'd also like to show you can submit fixes in the same format we use.
  20 [17:37] <jbicha> Run this command in Terminal:
  21 [17:37] <jbicha> bzr branch lp:ubuntu-docs
  22 [17:37] <jbicha> It may take a while depending on how fast your internet connection is, but that copies the source code from the Launchpad servers.
  23 [17:38] <jbicha> You can then use gedit or your favorite text editor to open up one of the pages.
  24 [17:38] <jbicha> Open up ubuntu-docs/ubuntu-help/help/C/unity-introduction.page for instance.
  25 [17:39] <jbicha> The first 20 lines or so are special information that sets the page title, keeps track of the page authors and the last time it was formally reviewed and other similar information.
  26 [17:39] <jbicha> Then you have the actual content. Each paragraph must start with <p> and end with </p>.
  27 [17:40] <jbicha> The Ubuntu Desktop Guide is written in Mallard (older docs or non-GNOME stuff use a similar but slightly more complex format named Docboook). More information about the format and a 10-minute introduction can be found at http://projectmallard.org/
  28 [17:41] <jbicha> The Mallard format is pretty cool as it is designed to be topic-based, as opposed to older computer help which read more like a manual or a book with chapters
  29 [17:43] <jbicha> We're trying to convert more and more GNOME apps to use it because it is more useful as I believe most people want to read an answer to their problem or a how-to for a specific task instead of trying to page through a longer document with chapters
  30 [17:44] <jbicha> We'd love it if other projects like KDE switched to the format too but that hasn't really happened yet
  31 [17:44] <jbicha> Anyway, you probably also want to bookmark http://blogs.gnome.org/shaunm/files/2012/01/mallardcheatsheet.png or https://gitorious.org/projectmallard/mallard-cheat-sheets/trees/master
  32 [17:45] <jbicha> that lets you see all the additional features you can add to your Mallard help files in one easy location
  33 [17:46] <jbicha> After you've made your changes (fixed a typo or added some extra information for instance), navigate in your terminal to the ubuntu-docs folder and run
  34 [17:46] <jbicha> bzr commit
  35 [17:47] <jbicha> This will open up nano (by default) where you should type in a description of what changes you've made. Then hit Ctrl+O to save and Ctrl+X to exit the editor.
  36 [17:47] <jbicha> Then you can run bzr push lp:~/ubuntu-docs/my-changes You'll want to definitely use something more descriptive than "my-changes" to describe what you've done.
  37 [17:48] <jbicha> Then open https://code.launchpad.net/~ in your web browser
  38 [17:48] <jbicha> Click the name of the branch you just pushed to
  39 [17:48] <jbicha> And then click the Propose for Merging button
  40 [17:49] <jbicha> the target branch should say lp:ubuntu-docs
  41 [17:49] <jbicha> you can add a description if you like, but you should probably leave the reviewer field blank, then click Propose Merge
  42 [17:50] <ClassBot> There are 10 minutes remaining in the current session.
  43 [17:50] <jbicha> If you have any questions, you can ask them now
  44 [17:51] <jbicha> Also, you can visit #ubuntu-docs or ask on our mailing list https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
  45 [17:55] <jbicha> the Ubuntu Documentation team and GNOME Docs team definitely could use your help
  46 [17:55] <ClassBot> There are 5 minutes remaining in the current session.
  47 [17:56] <jbicha> the Ubuntu Docs team is all-volunteer and we're always looking for more contributors
  48 [17:57] <ClassBot> jincreator asked: Can Mallard import ubuntu docs to pdf?
  49 [17:58] <jbicha> yes, you can but I'm going to have to get back with you about how that works
  50 [17:58] <jbicha> (since we're nearly out of time)
  51 [17:58] <jbicha> but Mallard already has exporters for html, xhtml, epub, and I believe pdf
  52 [17:59] <jbicha> thanks for your time!