Ubuntu Wiki

   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