DocsHelpWiki

Ubuntu Open Week - Docs Day - Working on the Help Wiki - MatthewEast / Rocket2DMn - Tue, Apr 28th, 2009

(04:01:54 PM) mdke: ok, I think perhaps we can get started with the next session
(04:03:31 PM) mdke: My name is Matthew East and I work with the Ubuntu Documentation Team
(04:03:55 PM) mdke: I'm going to be running this session with Connor Imes, Rocket2DMn, who works on the same team
(04:04:04 PM) mdke: The session is about the UBUNTU HELP WIKI
(04:04:22 PM) mdke: As those who have followed previous sessions know, we have five sessions today dealing with Ubuntu documentation. Two have already finished: an intro to the project, and translating documentation.
(04:04:52 PM) mdke: This session concentrates on one of the two main projects of the Ubuntu documentation team, the Ubuntu help wiki.
(04:05:05 PM) mdke: The last two sessions deal with the other main project, Ubuntu system documentation, which is the documentation that comes together with your Ubuntu desktop.
(04:05:26 PM) jcastro has changed the topic to: Welcome to Open Week || Session: 2000 UTC: Working on the help wiki  || https://wiki.ubuntu.com/UbuntuOpenWeek || All questions to #ubuntu-classroom-chat
(04:05:37 PM) mdke: The last two sessions, which emmajane will be running, deal with the other main project of the team, Ubuntu system documentation, which is the documentation that comes together with your Ubuntu desktop.
(04:05:59 PM) mdke: Both the system documentation and the help wiki are found in two sections of the same website: help.ubuntu.com
(04:06:08 PM) mdke: The system documentation is found at https://help.ubuntu.com/
(04:06:13 PM) mdke: The help wiki can be found here: https://help.ubuntu.com/community/
(04:06:35 PM) Rocket2DMn: The help wiki is also known as the Community Docs
(04:06:40 PM) mdke: By the way, feel free to shout my nick in #ubuntu-classroom-chat if I am going too fast
(04:07:08 PM) mdke: I'm going to use some dashes to separate different sections of the talk, so that it should be easier to read for those reviewing the log of the session
(04:07:16 PM) mdke: ---
(04:07:23 PM) mdke: I'll start by explaining what a "wiki" is.
(04:07:29 PM) mdke: A wiki is a website which anyone can edit.
(04:07:36 PM) mdke: It's a collaborative website that seeks to collect the knowledge of a large group of people.
(04:07:49 PM) mdke: The most famous example of course is wikipedia.
(04:08:01 PM) mdke: The Ubuntu community has several wikis. Among those are the team wiki (wiki.ubuntu.com) and the help wiki (help.ubuntu.com/community).
(04:08:19 PM) mdke: The difference is that the team wiki is used for coordination of the different teams in the Ubuntu community, while the help wiki is for users looking for documentation.
(04:08:41 PM) mdke: ---
(04:08:45 PM) mdke: Because anyone can edit the help wiki, quite a lot of attention is needed by volunteers to keep the wiki tidy, and to test the accuracy of material that is submitted.
(04:08:56 PM) mdke: It means that the wiki is a much more free-flowing resource than the system documentation, which go through a more rigorous process of quality control.
(04:09:11 PM) mdke: The wiki also has no limitations about how many subjects it can deal with, so we have much more information there than in the system documentation.
(04:09:31 PM) mdke: That can mean that it is less reliable, but it also means that it is an excellent resource for searching for the answers to more difficult problems.
(04:09:53 PM) mdke: It also means that it is a great place to start contributing - you don't need any special privileges to jump in and help out
(04:10:12 PM) mdke: Information produced on the wiki can also be road tested there so that it is later introduced into the system documentation.
(04:10:25 PM) mdke: ---
(04:10:31 PM) mdke: Ok, now I'm going to cover how to contribute to the help wiki.
(04:10:47 PM) mdke: We have a basic reference page which covers all the issues needed to contribute, which is https://help.ubuntu.com/community/WikiGuide - everyone contributing should have a look at that page.
(04:11:13 PM) mdke: Let me be very clear about one thing straight away - if you would like to contribute, and can't find the information you are curious about on that page - feel free to ask the Documentation team.
(04:11:21 PM) mdke: I'll give out the contact details towards the end of the session
(04:11:53 PM) mdke: Right, the first step is registering. It's necessary to have a Launchpad account in order to edit the wiki. This is to protect against automatic spam on the wiki.
(04:12:07 PM) mdke: Having a Launchpad account is pretty much a prerequisite for contributing in any way to the Ubuntu community, so you should definitely get one if you haven't already!
(04:12:38 PM) mdke: You can register for Launchpad here: https://launchpad.net (see the top right hand corner)
(04:12:56 PM) mdke: Once registered, you can log into the help wiki by visiting the wiki (https://help.ubuntu.com/community/) and clicking the "Login to Edit" text in the top right hand corner. This takes you to Launchpad, and you then enter your details and click "Continue".
(04:13:22 PM) mdke: ---
(04:13:31 PM) mdke: Once logged in, you can edit the page that you are viewing. The edit toolbar appears at the bottom of the screen when you click "Show editing options" in the bottom right.
(04:13:57 PM) mdke: To edit a page, click "Edit" in the toolbar. That shows you the "markup", or "raw text" that forms part of the wiki.
(04:14:25 PM) mdke: The markup is there to permit you to use formatting on the page. It's very similar to the wikipedia markup, but with some differences (we use different software to wikipedia)
(04:14:54 PM) mdke: Don't be scared by it, it's very simple and easy to learn. A simple edit to a page doesn't require any knowledge of markup, because you can just scroll to the relevant paragraph, and amend it, but I'll deal quickly with some basics now.
(04:15:16 PM) mdke: To create a title, we use this format:
(04:15:25 PM) mdke: = This is a heading =
(04:15:42 PM) mdke: You can also create sub-headings, by increasing the number of = signs, like this:
(04:15:50 PM) mdke: == This is a sub-heading ==
(04:16:08 PM) mdke: Paragraphs are very simple - you just leave a white line in between different paragraphs, like this:
(04:16:16 PM) mdke: This is the first paragraph
(04:16:26 PM) mdke: This is the second paragraph
(04:16:43 PM) mdke: (imagine we have a white line between the above two lines, I can't do it on irc)
(04:16:54 PM) Rocket2DMn: like this:
(04:16:58 PM) Rocket2DMn: paragraph 1
(04:16:59 PM) Rocket2DMn:  
(04:17:01 PM) Rocket2DMn: paragraph 2
(04:17:09 PM) mdke: nice! Thanks Rocket2DMn
(04:17:37 PM) mdke: To use text in italics, you put two inverted commas around the text in italics, like this:
(04:17:47 PM) mdke: This is a ''very good'' sentence.
(04:17:51 PM) Rocket2DMn: (apostrophes)
(04:17:59 PM) mdke: In that example, the words "very good" will appear in italics
(04:18:12 PM) mdke: sorry, apostrophes, yep
(04:18:36 PM) mdke: To use text in bold, you put three inverted commas around the text in bold, like this:
(04:18:54 PM) mdke: sorry again, apostrophes
(04:19:01 PM) mdke: This is a '''very good''' sentence.
(04:19:05 PM) mdke: You get the idea, I hope :)
(04:19:28 PM) mdke: Bulleted lists can be created by using the star sign:
(04:19:32 PM) mdke:  * Point 1 on the list
(04:19:37 PM) mdke:  * Point 2 on the list
(04:19:51 PM) mdke: Numbered lists can be created by using the number 1:
(04:19:59 PM) mdke:  1. Number 1 on the list
(04:20:07 PM) mdke:  1. Number 2 on the list
(04:20:12 PM) Rocket2DMn: Note the space at the beginning of the line.  This is required.
(04:20:29 PM) mdke: That looks a bit confusing, but it enables the wiki to ensure that the numbering is automatically updated if you add a line in the middle
(04:20:41 PM) mdke: You can do the same with letters:
(04:20:46 PM) mdke:  a. Letter a on the list
(04:20:50 PM) mdke:  a. Letter b on the list
(04:20:55 PM) mdke: and so on.
(04:21:12 PM) mdke: Links can be created quite simply too. You use this format:
(04:21:24 PM) mdke: [[http://www.ubuntu.com|Ubuntu website]]
(04:21:37 PM) mdke: In that example, the link text is "Ubuntu website" and the link target is www.ubuntu.com
(04:21:44 PM) mdke: That's really all you need to know to contribute whole pages to the wiki!
(04:21:48 PM) Rocket2DMn: The separator in the middle splits the link and the link text.
(04:21:59 PM) Rocket2DMn: The character is a pipe, above the Enter key on most keyboards
(04:22:29 PM) mdke: unless you are from the UK, in which case it's down in the bottom left above \
(04:22:32 PM) mdke: :)
(04:22:43 PM) jorge_ is now known as jcastro
(04:22:43 PM) mdke: See https://help.ubuntu.com/community/WikiGuide/Formatting for more detailed instructions about formatting on the wiki
(04:23:08 PM) mdke: I'd like to emphasise that you can contribute with very little experience of the markup at all, you should pick it up straight away and you can use the above page as a reference
(04:23:26 PM) mdke: We also have some writing style guidelines here: https://help.ubuntu.com/community/WikiGuide/WritingGuide
(04:23:42 PM) mdke: These give you some tips about the style which we'd like to be used on the wiki
(04:23:56 PM) mdke: Ok, I'll deal briefly with creating a whole new page
(04:24:21 PM) mdke: The easiest way to create a new page is simply to enter it's address in the address bar of your browser
(04:24:54 PM) mdke: so if you'd like to create the page called "LetsPractice", visit https://help.ubuntu.com/community/LetsPractice
(04:25:23 PM) mdke: I should say first that we use a specific naming convention on the wiki, which is to use CamelCase spellings for the title - this is like Title Case, but without the space between the words
(04:25:44 PM) mdke: See https://help.ubuntu.com/community/WikiGuide/PageCreation for more information about choosing a name
(04:25:58 PM) mdke: Back to our example - https://help.ubuntu.com/community/LetsPractice
(04:26:18 PM) mdke: If you visit that page, you'll see that the wiki is telling you that it doesn't exist yet
(04:26:34 PM) mdke: To create a new page, we have two options
(04:26:53 PM) mdke: The first is to create a blank page, which you do by clicking "Create new empty page"
(04:27:02 PM) mdke: The second is to create a page based on a template.
(04:27:35 PM) mdke: We use the "DocumentationTemplate" that you see on the left hand side. Clicking that will give you a new page with some suggested structure that you can use for a documentation page
(04:28:01 PM) mdke: ok, that's all for creating a page
(04:28:08 PM) mdke: for more information, please see https://help.ubuntu.com/community/WikiGuide/PageCreation
(04:28:24 PM) mdke: ---
(04:28:26 PM) mdke: Other than writing, once you have got used to the structure and guidelines of the wiki, you can also help a lot by helping to keep the wiki tidy.
(04:28:38 PM) mdke: We use "Tags" to keep the wiki tidy, and identify pages which need work in a particular area.
(04:29:09 PM) mdke: See https://help.ubuntu.com/community/Tag for more info
(04:29:35 PM) mdke: For an example of a tag in use, see https://help.ubuntu.com/community/VMware/Workstation
(04:29:50 PM) mdke: there you see a sign that the page deals with an unsupported version of Ubuntu
(04:30:06 PM) mdke: Tagging pages and cleaning up pages which already have tags is an amazingly useful way to contribute
(04:30:33 PM) mdke: I'd encourage people to have a read of the Tag page for more information
(04:30:37 PM) mdke: Users do not have permission on this wiki to delete or rename pages. Doing so can sometimes cause accidental, yet major, problems. This includes, but is not limited to, breaking links within the wiki itself and on the internet, as well as people's bookmarks. However, once you are familiar with the wiki, if you'd like to help out with its upkeep by deleting or renaming stray pages, you can apply to do so with the Ubuntu documentation team.
(04:30:50 PM) mdke: Again, I'll give out the contact details shortly
(04:31:40 PM) mdke: ---
(04:31:51 PM) mdke: Key tasks. The team has some particular key tasks to deal with. These are set out at this page: https://wiki.ubuntu.com/DocumentationTeam/Wiki/Tasks
(04:32:15 PM) mdke: I'm very conscious that this page is not as clear or structured as it should be, so it's fundamental that if you have any questions about where to contribute - please ask
(04:32:39 PM) mdke: Over the next few days and weeks we'll be working a lot on focusing the team's efforts on specific tasks, so watch this space!
(04:33:15 PM) mdke: One particular task I'd mention which is a good place to help out, is by replacing the out of date "Categories" on the wiki with our new Tag system
(04:33:21 PM) mdke: That's detailed here: https://help.ubuntu.com/community/WikiToDo/Tags
(04:33:52 PM) mdke: Another great task is to visit the pages which are marked for cleanup, and to tidy them up!
(04:33:56 PM) mdke: That's a never ending process...
(04:34:40 PM) mdke: Rocket2DMn: perhaps you could explain your "Summer of Documentation" initiative at this stage
(04:34:54 PM) Rocket2DMn: Sure
(04:35:16 PM) Rocket2DMn: Last summer we had a little effort to help get the help wiki up to date, and it became known as the Summer of Documentation
(04:35:47 PM) Rocket2DMn: It was initaited by the Beginners Team by members who also work with the doc team.  You can read about last year's here - https://wiki.ubuntu.com/BeginnersTeam/FocusGroups/Wiki/SoD2008
(04:36:10 PM) Rocket2DMn: We will be doing it again this year, but it is not limited to Beginners Team members, it is for the whole community.
(04:36:38 PM) Rocket2DMn: It will be focused on Tasks that the ubuntu doc team has set forward, like making use of tags and cleaning up outdated pages
(04:37:15 PM) Rocket2DMn: The idea is to get users who otherwise may not know how to contribute involved
(04:37:40 PM) Rocket2DMn: Let the doc team know if you are interested
(04:38:04 PM) mdke: ---
(04:38:10 PM) mdke: Last, but not least - communication
(04:38:29 PM) mdke: To get in touch with the Documentation Team, you can contact us via the mailing list or on irc chat
(04:38:46 PM) mdke: the mailing list is ubuntu-doc@lists.ubuntu.com, you can sign up here - http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
(04:38:59 PM) mdke: the irc channel in #ubuntu-doc on this network - feel free to join and hang around and ask questions
(04:39:22 PM) mdke: the channel is sometimes pretty quiet, depending on the time of day and the week, so don't be discouraged if you don't get a reply straight away - either hang around or send us an email
(04:39:31 PM) mdke: Full details about contacting the team are here: https://wiki.ubuntu.com/DocumentationTeam/Contact
(04:39:43 PM) mdke: ---
(04:40:07 PM) mdke: That's the end of the presentation part of the session, feel free to ask any questions now in #ubuntu-classroom-chat or by private message to me
(04:40:20 PM) mdke: We'll do our best to answer
(04:41:28 PM) mdke: QUESTION: is there any separate group for "Summer of Documentation"?
(04:42:25 PM) Rocket2DMn: ANSWER: No, there is no separate listing of members.  The Beginners Team Wiki Focus Group who hosts the Summer of Documentation does not keep a separate listing of involved members.  This helps keep us working as tightly with the doc team as possible
(04:42:41 PM) Rocket2DMn: It's all one effort.
(04:46:11 PM) mdke: QUESTION: actually just working on our wiki, and nobody seems to know how to add photos into a post?
(04:46:16 PM) ebel: czajkowski: *ping*
(04:46:38 PM) mdke: adding photos or screenshots to a wiki page is quite easy
(04:46:59 PM) mdke: you add them as an attachment using the "Attachments" button on the edit toolbar
(04:47:11 PM) mdke: Some detailed step by step instructions are here: https://help.ubuntu.com/community/WikiGuide/Screenshots
(04:48:17 PM) mdke: QUESTION: Is submitting fixes for documentation bugs the same as other packages?
(04:48:42 PM) mdke: ANSWER: in the case of bugs affecting the help wiki, it's a different process. You can simply log into the wiki and edit the page directly to fix the bug
(04:49:05 PM) mdke: in the case of bugs affecting the system documentation, we have a process which emmajane is going to describe for you in the next session :)
(04:53:12 PM) mdke: ok, that seems to be the end of the questions, so we'll take a short break of 5 minutes or so before we come back for the next session
(04:53:31 PM) mdke: feel free to contact the team if you have any questions about contributing

MeetingLogs/openweekJaunty/DocsHelpWiki (last edited 2009-04-28 21:12:21 by pool-70-16-48-183)