== Open Week -- Documentation is a big place: Learn how you can contribute to Ubuntu documentation -- Jim Campbell -- Thu, May 5 == {{{#!IRC [18:02] Logs for this session will be available at http://irclogs.ubuntu.com/2011/05/05/%23ubuntu-classroom.html following the conclusion of the session. [18:04] Hi everyone. Thanks for joining me today to talk about Documentation for Ubuntu! [18:04] It would be bad if the documentation folks didn't come prepared for their session with some words [18:04] but I also want you to be able to ask questions, so please feel free to ask questions when you have them. [18:04] So... Let's get started [18:04] The title of this session is, "Documentation is a big place: Learn how you can contribute to Ubuntu documentation," [18:05] and I've chosen that title for a reason. [18:05] There's a lot more to creating good user help than just being a good writer [18:05] and I think documentation can be a rewarding place to contribute, regardless of your skill set or area of interest. [18:06] This session is intended for people who are looking to contribute to Ubuntu user help in all of its forms. This includes: [18:06] Writers, editors, programmers, technical writers, translators, sysadmins, graphic designers, web developers, content strategists (people who help organize large amounts of information), and others. [18:06] a lot of different kinds of people! :) [18:06] This session will focus on these things: [18:07] - Who are our users, and what kind of help do we provide for them? [18:07] - The skills we use and the types of things we work on as part of contributing documentation for Ubuntu [18:07] - How you can get involved [18:07] sound good? [18:07] To get started with our first topic, what kind of help do we provide? [18:08] As you might expect, the list is pretty big [18:08] I will chunk-out some of the areas that we focus on. The items with an asterisk are currently handled by the "Ubuntu Core Docs" team [18:08] but you can look to contribute to other areas if you want to: [18:08] Let's start with desktop help [18:08] we have... [18:08] * The Ubuntu desktop guide (this is what you see when you search for 'help' in the Dash) [18:09] * Documentation for Kubuntu, Xubuntu, Ubuntu Studio, Mythbuntu, etc.) [18:09] */- Applications that are installed in Ubuntu (This could include stuff like from Gedit and the Software Center or even Ubuntu One) [18:09] I put an "*/-" in front of the application help because Ubuntu-docs team members are very good about contributing upstream application help. [18:10] but not all of it is done by us [18:10] Ubuntu docs people have written help for Banshee, gedit, evince, Empathy, and more. [18:10] We also wrote huge portions of the Gnome3 help. [18:10] We have a great relationship between upstream Gnome docs and Ubuntu docs, and we work together to help each other out. [18:11] There is also the Ubuntu Manual (technically, the Ubuntu Manual project is a separate project, but they are a group that is producing help for Ubuntu, too, and our camps are starting to bridge a little bit.) [18:11] ... is my pace ok for you all? :) [18:12] no comments mean i guess my pace is ok [18:12] :) [18:12] ok... but we do more than desktop help [18:12] there is also server docs and Ubuntu infrastructure help [18:12] The Ubuntu Server Guide ( /me looks at sysadmins... ಠ_ಠ) [18:13] There is also Ubuntu Cloud documentation (This is a discussion for the coming UDS...) [18:13] The Ubuntu Packaging Guide (still a work-in-progress, but it's coming along!) [18:13] Developer documentation [18:13] Just to reiterate, these aren't *all* handled by the Docs team, but there is room to contribute in all of these areas if any of them strike your fancy. There are a few other areas, too: [18:14] The Ubuntu wiki: a wiki written for those who want to contribute to Ubuntu: https://wiki.ubuntu.com [18:14] All of the "team" stuff for various Ubuntu teams is there. It is largely maintained by the individual teams. There are lots of teams. [18:14] The docs team has our own wiki page on there, too. https://wiki.ubuntu.com/DocumentationTeam [18:14] more on that later, though. [18:15] We also have the Ubuntu Community wiki (a wiki written for users, by users: https://help.ubuntu.com/community ) [18:15] Some people file bugs against the community wiki in Launchpad, but it is not maintained by the docs team. You can edit it yourself! [18:15] That is most of my list, though... [18:15] Has this list made you want to cry? [18:15] How can we approach all of this help? [18:15] Isn't documentation supposed to be boring? [18:16] Although a large part of creating documentation involves the actual writing, creating good user help involves a lot of different skills. [18:16] Now that we have explored what all we produce, I would like to transition to my second topic: what skills and areas of expertise we use (or want to start using!) to create all of that user help. [18:16] before I do so, though... [18:16] let me look for questions. remember to precede your question by typing QUESTION: [18:17] someone asked: im noticing alot of chatter on translation list about translating the ubuntu docs for each loco team how is that being moved forward [18:17] we were late with the 11.04 docs (for various reasons) [18:17] we have now opened up the docs for translations, though [18:18] and will be doing stable-release updates for 11.04 [18:18] as more docs are translated [18:18] things will be much better for the 11.10 release, though [18:18] thank you for that question! [18:19] ok... what kinds of skills do we use? what approaches do we take as part of the project to produce this work? [18:19] Of course, there is writing, but what else is in our list? [18:19] Editing (lots of revisions), Application programming (programming the front- and back-end of the help browser ... yes, some hackers work on documentation!) [18:19] XML Schema development (Hack, code, hack, code... drink coffee), Refining our XSLT transformations (Woo! More hackers!) [18:20] Packaging skills for getting the documentation into Ubuntu, Providing documentation updates in prior releases [18:20] Collaborating with translation teams to translate the documentation [18:20] wiki maintenance [18:20] bug triage [18:20] Graphics and Design (there are pictures in Ubuntu docs now... welcome to the future) [18:20] Web Development (This is a bit of a 'future development'...) [18:20] Content strategy (This is stuff like style guides, accessibility guidelines, content templates, taxonomies, user personas, workflow recommendations, etc.) [18:21] see, there's lots of places to dig in! [18:21] you don't have to be a programmer to help out, but those are just some of the areas where you *can* help out [18:21] with so many choices, it might seem overwhelming [18:22] If documentation is a big place, how can you find your own room? [18:22] will there be people down the hall that you can talk to? [18:22] how can you find the bathroom? :( [18:22] Ok, maybe I'm taking that metaphor too far, but the question is, "How can you get involved? Where can you get get started?" [18:22] Wow, what a nice segue to my next topic [18:23] how you can get involved [18:23] The most important part of just to pick something that interests you. [18:23] Take some time to consider it, what would be neat to work on? [18:23] What do you think you might be good at? [18:23] Where is there work that needs to be done? [18:24] The teams are somewhat separate between Ubuntu, Kubuntu and Xubuntu [18:24] but we all work together under the same umbrella [18:24] We're all part of the larger docs team [18:24] Once you have a rough idea of where you may want to contribute, dig in. [18:24] ask questions [18:24] With the Ubuntu Docs team, the best way to get involved is to join our mailing list, and introduce yourself. [18:25] The mailing list is here: https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc [18:25] Don't fret over not knowing enough or put a lot of pressure on yourself--it takes time to learn. [18:25] If you pick something that you think will be interesting, and then later find out that it is boring and lame, you can switch to something else. It can take a while to find your niche. [18:26] You can also peruse our archives to see what kinds of topics we've been talking about lately: https://lists.ubuntu.com/archives/ubuntu-doc/ [18:26] In your introduction, you should explain a little about yourself, what drew you to the team, what skills you have, and what you may be interested in working on. [18:26] In your introduction, you should explain a little about yourself, what drew you to the team, what skills you have, and what you may be interested in working on... [18:27] and you could contribute to documentation for that feature. [18:27] Or maybe you know a lot about packaging, you could contribute to the Ubuntu Packaging Guide. [18:27] The team has worked a lot to improve our help for 11.04, but there is still a lot more to do [18:27] We are in the process of laying out some strategic goals [18:27] as well as some specific goals for 11.10 [18:27] so now is a great time to get involved [18:28] We have two blueprints that are lined up for this coming UDS. One on strategy, and one on our goals for the 11.10 release. [18:28] https://blueprints.launchpad.net/ubuntu/+spec/desktop-o-ubuntu-docs-strategy [18:28] https://blueprints.launchpad.net/ubuntu/+spec/community-o-ubuntu-docs-goals-oneiric [18:28] If you join the mailing list now, you'll be in a great spot to identify areas where you can contribute for this coming release. [18:28] Briefly, some big-picture areas that we're looking to focus on include better help on the web, leveraging community-based help, and building Ubuntu as a platform for technical writers. [18:29] There are lots of deliverables included in that, and we'll need to identify particular goals for each release that will get us closer to those long-term goals. [18:29] our team wiki has info about how to join the team: https://wiki.ubuntu.com/DocumentationTeam [18:29] And there is a contributors page in launchpad: https://launchpad.net/~ubuntu-doc-contributors [18:30] On IRC, we hang out in #ubuntu-doc on the freenode network (this one!) [18:30] *** ~~~ *** ~~~ *** ~~~ *** [18:30] : ) [18:30] That is most of what I had prepared to talk about today, so now we have some extra time to go over things [18:30] ask / answer questions [18:31] Talk about how much we're improving docs [18:31] please remember to start your questions with QUESTION [18:34] shaunm asks: how many documents is ubuntu-core-doc in charge of? [18:34] i'd have to look, but in the documentation that we shipped with 11.04, I think we had about 170 different topics [18:35] for this release we worked largely off of upstream gnome documentation, and adapted it for ubuntu [18:35] that's another thing about picking an area that interests you [18:35] if you use a lot of the graphics tools... [18:36] you can contribute to the user help for shotwell (the app in ubuntu for handling your photos) [18:36] or you could even contribute to upstream inkscape or gimp help [18:36] of course, if you're a graphics pro (or want to be one), we could use your assistance with the images in ubuntu docs === medberry is now known as med_out [18:38] another question asked what i meant by upstream... other distros using unity as an interface [18:38] i meant it more in the sense of gnome 3's interface [18:38] we used much of the structure that we created for gnome 3 help (the help layout) for the ubuntu 11.04 help [18:39] we will be tinkering with the layout a bit for 11.10, though [18:39] and will be working with gnome folks as we make those adjustments [18:39] share and share alike. :) [18:40] there is a lot of innovation going on in open-source help now, though. [18:40] this is good, because there is a lot of *room* for innovation at this time. :) [18:40] we want to make free software user help top notch [18:41] one area that i forgot to mention includes OEMs [18:41] in a way, OEMs (original equipment manufacturers) are *downstream* of ubuntu docs [18:42] they can take what we create, and tweak it to suit their product [18:42] we want to make sure that our user help is appropriate for them, as well [18:43] In terms of the future direction for the docs: some of the enhancements that we are looking at include [18:43] - context-sensitive help [18:43] ... so if you're using Unity 2-d, you will automatically see help that is appropriate for the 2d version [18:44] ... or if you're using Kubuntu, you would see Kubuntu help [18:44] all automatically [18:44] - faceted navigation [18:44] ... so you can see only those topic areas that you are interested in [18:44] - a much more robust web presence [18:45] We're also in touch with folks from KDE to work together on a help browser that will integrate better with online help [18:46] If you have ideas around any of these topics, or if you just want to help with writing help for Ubuntu... [18:46] you are welcome to join us. : ) [18:48] thanks very much for your time today, everyone. :) [18:50] joksher asked: Question:so far i've only seen user documentation, i mean a more friendly docs, there are any place where i can find a more detailed doc about the system wide. [18:51] It sounds like you're asking for more broad-based user help... not just help on a particular topic... [18:51] but more generalized help on just using the system . [18:51] for that, i would recommend the ubuntu manual. [18:51] the 11.04 manual isn't out yet, but they are working to get one out. [18:52] There are 10 minutes remaining in the current session. [18:52] saimanoj52 asked about how to contribute through code. and how to learn how to contribute through code [18:52] for that i would look to some of the gnome documentation developer tutorials and look to the ubuntu packaging guide [18:52] if you go to library.gnome.org ... [18:53] you will find the developer tutorials [18:53] daniel holbach recently put up a blog post about the packaging guide [18:53] so if you search for his blog, you will find info on it [18:54] other questions? [18:54] (there is also a packaging guide on the wiki... but... [18:54] this new project is set to replace that [18:54] ) [18:55] it will be easier to maintain the packaging guide in a non-wiki format, and it will be easier to translate, too. [18:56] just as a gentle nudge... if you're at all interested, join the mailing list and send us an introductory note. [18:56] thanks very much for your time today, everyone. :) [18:57] There are 5 minutes remaining in the current session. [19:02] Logs for this session will be available at http://irclogs.ubuntu.com/2011/05/05/%23ubuntu-classroom.html }}}