Dev Week -- Getting started with contributing to Ubuntu Documentation -- jbicha -- Thu, 3rd Feb, 2012
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!