Open Week -- Documentation is a big place: Learn how you can contribute to Ubuntu documentation -- Jim Campbell -- Thu, May 5
1 [18:02] <ClassBot> Logs for this session will be available at http://irclogs.ubuntu.com/2011/05/05/%23ubuntu-classroom.html following the conclusion of the session.
2 [18:04] <j1mc> Hi everyone. Thanks for joining me today to talk about Documentation for Ubuntu!
3 [18:04] <j1mc> It would be bad if the documentation folks didn't come prepared for their session with some words
4 [18:04] <j1mc> but I also want you to be able to ask questions, so please feel free to ask questions when you have them.
5 [18:04] <j1mc> So... Let's get started
6 [18:04] <j1mc> The title of this session is, "Documentation is a big place: Learn how you can contribute to Ubuntu documentation,"
7 [18:05] <j1mc> and I've chosen that title for a reason.
8 [18:05] <j1mc> There's a lot more to creating good user help than just being a good writer
9 [18:05] <j1mc> and I think documentation can be a rewarding place to contribute, regardless of your skill set or area of interest.
10 [18:06] <j1mc> This session is intended for people who are looking to contribute to Ubuntu user help in all of its forms. This includes:
11 [18:06] <j1mc> Writers, editors, programmers, technical writers, translators, sysadmins, graphic designers, web developers, content strategists (people who help organize large amounts of information), and others.
12 [18:06] <j1mc> a lot of different kinds of people! :)
13 [18:06] <j1mc> This session will focus on these things:
14 [18:07] <j1mc> - Who are our users, and what kind of help do we provide for them?
15 [18:07] <j1mc> - The skills we use and the types of things we work on as part of contributing documentation for Ubuntu
16 [18:07] <j1mc> - How you can get involved
17 [18:07] <j1mc> sound good?
18 [18:07] <j1mc> To get started with our first topic, what kind of help do we provide?
19 [18:08] <j1mc> As you might expect, the list is pretty big
20 [18:08] <j1mc> 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
21 [18:08] <j1mc> but you can look to contribute to other areas if you want to:
22 [18:08] <j1mc> Let's start with desktop help
23 [18:08] <j1mc> we have...
24 [18:08] <j1mc> * The Ubuntu desktop guide (this is what you see when you search for 'help' in the Dash)
25 [18:09] <j1mc> * Documentation for Kubuntu, Xubuntu, Ubuntu Studio, Mythbuntu, etc.)
26 [18:09] <j1mc> */- Applications that are installed in Ubuntu (This could include stuff like from Gedit and the Software Center or even Ubuntu One)
27 [18:09] <j1mc> I put an "*/-" in front of the application help because Ubuntu-docs team members are very good about contributing upstream application help.
28 [18:10] <j1mc> but not all of it is done by us
29 [18:10] <j1mc> Ubuntu docs people have written help for Banshee, gedit, evince, Empathy, and more.
30 [18:10] <j1mc> We also wrote huge portions of the Gnome3 help.
31 [18:10] <j1mc> We have a great relationship between upstream Gnome docs and Ubuntu docs, and we work together to help each other out.
32 [18:11] <j1mc> 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.)
33 [18:11] <j1mc> ... is my pace ok for you all? :)
34 [18:12] <j1mc> no comments mean i guess my pace is ok
35 [18:12] <j1mc> :)
36 [18:12] <j1mc> ok... but we do more than desktop help
37 [18:12] <j1mc> there is also server docs and Ubuntu infrastructure help
38 [18:12] <j1mc> The Ubuntu Server Guide ( /me looks at sysadmins... ಠ_ಠ)
39 [18:13] <j1mc> There is also Ubuntu Cloud documentation (This is a discussion for the coming UDS...)
40 [18:13] <j1mc> The Ubuntu Packaging Guide (still a work-in-progress, but it's coming along!)
41 [18:13] <j1mc> Developer documentation
42 [18:13] <j1mc> 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:
43 [18:14] <j1mc> The Ubuntu wiki: a wiki written for those who want to contribute to Ubuntu: https://wiki.ubuntu.com
44 [18:14] <j1mc> All of the "team" stuff for various Ubuntu teams is there. It is largely maintained by the individual teams. There are lots of teams.
45 [18:14] <j1mc> The docs team has our own wiki page on there, too. https://wiki.ubuntu.com/DocumentationTeam
46 [18:14] <j1mc> more on that later, though.
47 [18:15] <j1mc> We also have the Ubuntu Community wiki (a wiki written for users, by users: https://help.ubuntu.com/community )
48 [18:15] <j1mc> Some people file bugs against the community wiki in Launchpad, but it is not maintained by the docs team. You can edit it yourself!
49 [18:15] <j1mc> That is most of my list, though...
50 [18:15] <j1mc> Has this list made you want to cry?
51 [18:15] <j1mc> How can we approach all of this help?
52 [18:15] <j1mc> Isn't documentation supposed to be boring?
53 [18:16] <j1mc> Although a large part of creating documentation involves the actual writing, creating good user help involves a lot of different skills.
54 [18:16] <j1mc> 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.
55 [18:16] <j1mc> before I do so, though...
56 [18:16] <j1mc> let me look for questions. remember to precede your question by typing QUESTION:
57 [18:17] <j1mc> 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
58 [18:17] <j1mc> we were late with the 11.04 docs (for various reasons)
59 [18:17] <j1mc> we have now opened up the docs for translations, though
60 [18:18] <j1mc> and will be doing stable-release updates for 11.04
61 [18:18] <j1mc> as more docs are translated
62 [18:18] <j1mc> things will be much better for the 11.10 release, though
63 [18:18] <j1mc> thank you for that question!
64 [18:19] <j1mc> ok... what kinds of skills do we use? what approaches do we take as part of the project to produce this work?
65 [18:19] <j1mc> Of course, there is writing, but what else is in our list?
66 [18:19] <j1mc> Editing (lots of revisions), Application programming (programming the front- and back-end of the help browser ... yes, some hackers work on documentation!)
67 [18:19] <j1mc> XML Schema development (Hack, code, hack, code... drink coffee), Refining our XSLT transformations (Woo! More hackers!)
68 [18:20] <j1mc> Packaging skills for getting the documentation into Ubuntu, Providing documentation updates in prior releases
69 [18:20] <j1mc> Collaborating with translation teams to translate the documentation
70 [18:20] <j1mc> wiki maintenance
71 [18:20] <j1mc> bug triage
72 [18:20] <j1mc> Graphics and Design (there are pictures in Ubuntu docs now... welcome to the future)
73 [18:20] <j1mc> Web Development (This is a bit of a 'future development'...)
74 [18:20] <j1mc> Content strategy (This is stuff like style guides, accessibility guidelines, content templates, taxonomies, user personas, workflow recommendations, etc.)
75 [18:21] <j1mc> see, there's lots of places to dig in!
76 [18:21] <j1mc> you don't have to be a programmer to help out, but those are just some of the areas where you *can* help out
77 [18:21] <j1mc> with so many choices, it might seem overwhelming
78 [18:22] <j1mc> If documentation is a big place, how can you find your own room?
79 [18:22] <j1mc> will there be people down the hall that you can talk to?
80 [18:22] <j1mc> how can you find the bathroom? :(
81 [18:22] <j1mc> Ok, maybe I'm taking that metaphor too far, but the question is, "How can you get involved? Where can you get get started?"
82 [18:22] <j1mc> Wow, what a nice segue to my next topic
83 [18:23] <j1mc> how you can get involved
84 [18:23] <j1mc> The most important part of just to pick something that interests you.
85 [18:23] <j1mc> Take some time to consider it, what would be neat to work on?
86 [18:23] <j1mc> What do you think you might be good at?
87 [18:23] <j1mc> Where is there work that needs to be done?
88 [18:24] <j1mc> The teams are somewhat separate between Ubuntu, Kubuntu and Xubuntu
89 [18:24] <j1mc> but we all work together under the same umbrella
90 [18:24] <j1mc> We're all part of the larger docs team
91 [18:24] <j1mc> Once you have a rough idea of where you may want to contribute, dig in.
92 [18:24] <j1mc> ask questions
93 [18:24] <j1mc> With the Ubuntu Docs team, the best way to get involved is to join our mailing list, and introduce yourself.
94 [18:25] <j1mc> The mailing list is here: https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
95 [18:25] <j1mc> Don't fret over not knowing enough or put a lot of pressure on yourself--it takes time to learn.
96 [18:25] <j1mc> 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.
97 [18:26] <j1mc> 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/
98 [18:26] <j1mc> 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.
99 [18:26] <j1mc> 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...
100 [18:27] <j1mc> and you could contribute to documentation for that feature.
101 [18:27] <j1mc> Or maybe you know a lot about packaging, you could contribute to the Ubuntu Packaging Guide.
102 [18:27] <j1mc> The team has worked a lot to improve our help for 11.04, but there is still a lot more to do
103 [18:27] <j1mc> We are in the process of laying out some strategic goals
104 [18:27] <j1mc> as well as some specific goals for 11.10
105 [18:27] <j1mc> so now is a great time to get involved
106 [18:28] <j1mc> 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.
107 [18:28] <j1mc> https://blueprints.launchpad.net/ubuntu/+spec/desktop-o-ubuntu-docs-strategy
108 [18:28] <j1mc> https://blueprints.launchpad.net/ubuntu/+spec/community-o-ubuntu-docs-goals-oneiric
109 [18:28] <j1mc> 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.
110 [18:28] <j1mc> 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.
111 [18:29] <j1mc> 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.
112 [18:29] <j1mc> our team wiki has info about how to join the team: https://wiki.ubuntu.com/DocumentationTeam
113 [18:29] <j1mc> And there is a contributors page in launchpad: https://launchpad.net/~ubuntu-doc-contributors
114 [18:30] <j1mc> On IRC, we hang out in #ubuntu-doc on the freenode network (this one!)
115 [18:30] <j1mc> *** ~~~ *** ~~~ *** ~~~ ***
116 [18:30] <j1mc> : )
117 [18:30] <j1mc> That is most of what I had prepared to talk about today, so now we have some extra time to go over things
118 [18:30] <j1mc> ask / answer questions
119 [18:31] <j1mc> Talk about how much we're improving docs
120 [18:31] <j1mc> please remember to start your questions with QUESTION
121 [18:34] <j1mc> shaunm asks: how many documents is ubuntu-core-doc in charge of?
122 [18:34] <j1mc> i'd have to look, but in the documentation that we shipped with 11.04, I think we had about 170 different topics
123 [18:35] <j1mc> for this release we worked largely off of upstream gnome documentation, and adapted it for ubuntu
124 [18:35] <j1mc> that's another thing about picking an area that interests you
125 [18:35] <j1mc> if you use a lot of the graphics tools...
126 [18:36] <j1mc> you can contribute to the user help for shotwell (the app in ubuntu for handling your photos)
127 [18:36] <j1mc> or you could even contribute to upstream inkscape or gimp help
128 [18:36] <j1mc> of course, if you're a graphics pro (or want to be one), we could use your assistance with the images in ubuntu docs
129 === medberry is now known as med_out
130 [18:38] <j1mc> another question asked what i meant by upstream... other distros using unity as an interface
131 [18:38] <j1mc> i meant it more in the sense of gnome 3's interface
132 [18:38] <j1mc> we used much of the structure that we created for gnome 3 help (the help layout) for the ubuntu 11.04 help
133 [18:39] <j1mc> we will be tinkering with the layout a bit for 11.10, though
134 [18:39] <j1mc> and will be working with gnome folks as we make those adjustments
135 [18:39] <j1mc> share and share alike. :)
136 [18:40] <j1mc> there is a lot of innovation going on in open-source help now, though.
137 [18:40] <j1mc> this is good, because there is a lot of *room* for innovation at this time. :)
138 [18:40] <j1mc> we want to make free software user help top notch
139 [18:41] <j1mc> one area that i forgot to mention includes OEMs
140 [18:41] <j1mc> in a way, OEMs (original equipment manufacturers) are *downstream* of ubuntu docs
141 [18:42] <j1mc> they can take what we create, and tweak it to suit their product
142 [18:42] <j1mc> we want to make sure that our user help is appropriate for them, as well
143 [18:43] <j1mc> In terms of the future direction for the docs: some of the enhancements that we are looking at include
144 [18:43] <j1mc> - context-sensitive help
145 [18:43] <j1mc> ... so if you're using Unity 2-d, you will automatically see help that is appropriate for the 2d version
146 [18:44] <j1mc> ... or if you're using Kubuntu, you would see Kubuntu help
147 [18:44] <j1mc> all automatically
148 [18:44] <j1mc> - faceted navigation
149 [18:44] <j1mc> ... so you can see only those topic areas that you are interested in
150 [18:44] <j1mc> - a much more robust web presence
151 [18:45] <j1mc> We're also in touch with folks from KDE to work together on a help browser that will integrate better with online help
152 [18:46] <j1mc> If you have ideas around any of these topics, or if you just want to help with writing help for Ubuntu...
153 [18:46] <j1mc> you are welcome to join us. : )
154 [18:48] <j1mc> thanks very much for your time today, everyone. :)
155 [18:50] <j1mc> 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.
156 [18:51] <j1mc> It sounds like you're asking for more broad-based user help... not just help on a particular topic...
157 [18:51] <j1mc> but more generalized help on just using the system .
158 [18:51] <j1mc> for that, i would recommend the ubuntu manual.
159 [18:51] <j1mc> the 11.04 manual isn't out yet, but they are working to get one out.
160 [18:52] <ClassBot> There are 10 minutes remaining in the current session.
161 [18:52] <j1mc> saimanoj52 asked about how to contribute through code. and how to learn how to contribute through code
162 [18:52] <j1mc> for that i would look to some of the gnome documentation developer tutorials and look to the ubuntu packaging guide
163 [18:52] <j1mc> if you go to library.gnome.org ...
164 [18:53] <j1mc> you will find the developer tutorials
165 [18:53] <j1mc> daniel holbach recently put up a blog post about the packaging guide
166 [18:53] <j1mc> so if you search for his blog, you will find info on it
167 [18:54] <j1mc> other questions?
168 [18:54] <j1mc> (there is also a packaging guide on the wiki... but...
169 [18:54] <j1mc> this new project is set to replace that
170 [18:54] <j1mc> )
171 [18:55] <j1mc> it will be easier to maintain the packaging guide in a non-wiki format, and it will be easier to translate, too.
172 [18:56] <j1mc> just as a gentle nudge... if you're at all interested, join the mailing list and send us an introductory note.
173 [18:56] <j1mc> thanks very much for your time today, everyone. :)
174 [18:57] <ClassBot> There are 5 minutes remaining in the current session.
175 [19:02] <ClassBot> Logs for this session will be available at http://irclogs.ubuntu.com/2011/05/05/%23ubuntu-classroom.html