Ubuntu Wiki

Ubuntu Open Week - Docs Day - Intro to the Docs Team - DougieRichardson - Tue, Apr 28th, 2009

(02:02:24 PM) DougieRichardson: Hi everyone and welcome to Docs Day
(02:03:25 PM) DougieRichardson: We've got five slots today and hope to cover most everything that the Documentation Team does
(02:04:03 PM) DougieRichardson: I'll start by introducing myself
(02:04:31 PM) DougieRichardson: I'm Dougie and up until I joined the Doc's team I'd had no experience at all with writing documentation or using DocBook
(02:05:17 PM) koolhead17 left the room.
(02:05:20 PM) DougieRichardson: I maintain the Internet and Networking sections of the System Help but help out in other areas too
(02:05:27 PM) mib_0oi9gt: is the q and a with mark over?
(02:05:48 PM) DougieRichardson: There are five sessions tonight - an intro
(02:05:54 PM) DougieRichardson: Translations
(02:06:15 PM) DougieRichardson: A session on adding and working with the community help wiki
(02:06:27 PM) DougieRichardson: Getting the docs and using Bzr
(02:06:34 PM) DougieRichardson: and lastly working with DocBook
(02:07:04 PM) DougieRichardson: DocBook is an XML markup language that is used not only in Ubuntu's help but upstream too
(02:07:24 PM) DougieRichardson: Documentation in Ubuntu is split into two main areas
(02:07:41 PM) DougieRichardson: The system help, which you access through Yelp
(02:08:03 PM) DougieRichardson: And the community contributed documentation which is available at http://help.ubuntu.com/community
(02:08:33 PM) DougieRichardson: There are two types because we want to offer a full range of help to everyone, which is where the wiki is useful
(02:09:07 PM) DougieRichardson: and having more commonly asked tasks available without an internet connection
(02:09:37 PM) DougieRichardson: Subjects such as connecting to the internet is obviously needed offline!
(02:10:20 PM) DougieRichardson: The system help is split into sections and is available for different flavours of Ubuntu
(02:10:59 PM) DougieRichardson: it is written using DocBook XML, which is a markup language.
(02:11:26 PM) DougieRichardson: We are often asked why we use this but there are advantages to it - it can be easily processed into other formats
(02:11:38 PM) DougieRichardson: Such as HTML and PDF
(02:12:01 PM) DougieRichardson: Which allows us to generate the same information for access on the internet
(02:12:31 PM) DougieRichardson: Upstream also uses the same format, so we can share our documentation upstream too.
(02:13:16 PM) DougieRichardson: The community documentation wiki is editable by anyone with a Launchpad account
(02:14:04 PM) DougieRichardson: The wiki is seperate to http:/wiki.ubuntu.com which is only for team use
(02:14:49 PM) DougieRichardson: Its an ideal place for new contributers to start, because it is very accessible and the syntax is simpler than XML
(02:15:46 PM) DougieRichardson: The documentation team is organised into three teams
(02:15:57 PM) DougieRichardson: Ubuntu documentation contributers
(02:16:23 PM) DougieRichardson: Who can: edit wiki pages, traige and report bugs, contribute patches and participate in the teams discussions
(02:16:54 PM) DougieRichardson: we particularly welcome discussion from new contributers so we can produce the sort of documentation that is actually asked for
(02:17:49 PM) DougieRichardson: We have Ubuntu documentation commiters, which are much the same as contributers except they have displayed understanding of the tool chain and have access to the ubuntu-docs package, so can commit changes.
(02:18:47 PM) DougieRichardson: Lastly, we have Ubuntu documentation wiki admins who again do the same as contributers but have displayed a strong understanding of the wiki (in particualr deletion and the effects of renaming pages) and have access to delete and rename pages.
(02:19:19 PM) DougieRichardson: Joining the team is easy - just apply on Launchpad and introduce yourself on the mailing list
(02:19:35 PM) DougieRichardson: https://launchpad.net/ubuntu-doc
(02:19:48 PM) DougieRichardson: and the ML is https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
(02:20:38 PM) DougieRichardson: The team has members from all over the world so with difference in time zones tends to do most of its discussion via the mailing list.
(02:21:13 PM) DougieRichardson: We do hold meetings though whenever possible and anyon is welcome to join us on IRC #ubuntu-doc on this very server
(02:21:40 PM) DougieRichardson: So where do you get started?
(02:22:15 PM) DougieRichardson: The best place to start is by checking out current bugs
(02:22:34 PM) DougieRichardson: There are four pages used, one for each Ubuntu
(02:22:42 PM) DougieRichardson: http://bugs.launchpad.net/ubuntu/+source/ubuntu-docs
(02:22:43 PM) DougieRichardson:       http://bugs.launchpad.net/ubuntu/+source/kubuntu-docs
(02:22:43 PM) DougieRichardson:       http://bugs.launchpad.net/ubuntu/+source/xubuntu-docs
(02:22:43 PM) DougieRichardson:       http://bugs.launchpad.net/ubuntu/+source/edubuntu-docs
(02:23:13 PM) DougieRichardson: Pick a bug, assign it to yourself and get fixing!
(02:23:37 PM) DougieRichardson: There are several guides available on our team site and there is the newly produced Playbook
(02:23:49 PM) DougieRichardson: (I'll cover this more later)
(02:24:38 PM) DougieRichardson: Fixing bugs is fairly straightforward, most bugs are simply typos or corrections for new versions
(02:25:10 PM) DougieRichardson: Once you have the source (which Matthew will cover at 2100 UTC)
(02:25:24 PM) DougieRichardson: You can look over the docs and change the errant strings.
(02:25:49 PM) DougieRichardson: What if you're more interested in the wiki?
(02:26:05 PM) DougieRichardson: There are a list of areas that need work in the Wiki
(02:26:14 PM) DougieRichardson: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks
(02:26:33 PM) DougieRichardson: Sorry, wrong: https://wiki.ubuntu.com/DocumentationTeam/Wiki/Tasks
(02:27:28 PM) DougieRichardson: The wiki has a lot of pages that need cleaned up
(02:27:57 PM) DougieRichardson: There is a lot of information that should be moved from the team wiki to the help wiki
(02:28:06 PM) DougieRichardson: Articles that need expanding
(02:28:40 PM) DougieRichardson: And we're always keen to integrate some of the fantastic howtos and guides that are available on the Ubuntu Forums into the help wiki
(02:29:23 PM) DougieRichardson: This release cycle, we have three new initiatives to announce too.
(02:30:29 PM) DougieRichardson: First, we are producing a series of "Playbooks", single A4 PDF covering our tool chain and processes
(02:30:55 PM) DougieRichardson: The first is available and has already been used by new members to submit patches!
(02:31:37 PM) DougieRichardson: Its available from my personal web site at the moment and once the others are available will be moved onto Launchpad and linked from the team site: http://www.lynxworks.eu/files/BugsPlaybook.pdf
(02:32:20 PM) DougieRichardson: I'd love it if this was passed around as much as possible, even better if it was printed out and distributed at LoCo events, or your work/college wherever.
(02:32:51 PM) DougieRichardson: We are now accepting submissions for larger articles as plain text without markup.
(02:33:22 PM) DougieRichardson: An Ubuntu Documentation Commiter will wrap it in XML and push it to the branch.
(02:33:47 PM) DougieRichardson: We appreciate that not everyone has the time or interest to learn XML so we're happy to offer this for large submissions.
(02:34:11 PM) DougieRichardson: We are running a series of IRC lessons
(02:34:31 PM) DougieRichardson: The first of which will be announced soon on our mailing list and on the Planet.
(02:35:09 PM) DougieRichardson: I'll be taking a bug on Launchpad and go through all the steps to fix it in slow time, providing a recap sheet at the end.
(02:35:38 PM) DougieRichardson: These lessons will be staggered so that different time zones can benefit too.
(02:36:43 PM) DougieRichardson: Lastly we are introducing "Doc Days" - much likethe QA team has done, we will nominate an area, particularly of the wiki and try and achieve as much community participation as possible in that area on a single day.
(02:37:33 PM) DougieRichardson: Again this will be announced soon via the mailing list and via the Planet
(02:38:52 PM) DougieRichardson: There is also a large push towards revamping the current switching from windows guide to a new installation guide
(02:39:32 PM) DougieRichardson: Any contributions to this effort will be very much appreciated, where we intend to try and gather the most common installation problems
(02:39:49 PM) DougieRichardson: and cover them - so we need as many installation problems as possible reported!
(02:40:32 PM) DougieRichardson: Submit any problems you've found to https://wiki.ubuntu.com/Specs/KarmicInstallationGuide#Common%20problems%20for%20the%20Troubleshooting%20section
(02:41:24 PM) DougieRichardson: So that pretty much wraps up the introduction to Docs Day but before I take any questions, I'd like to recap on contacting us:
(02:41:40 PM) DougieRichardson: Wiki Page    https://wiki.ubuntu.com/DocumentationTeam
(02:41:40 PM) DougieRichardson: Launchpad    https://launchpad.net/ubuntu-doc
(02:41:40 PM) DougieRichardson: Mailing list https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
(02:41:40 PM) DougieRichardson: List archive https://lists.ubuntu.com/archives/ubuntu-doc/
(02:41:40 PM) DougieRichardson: IRC          #ubuntu-doc on irc.freenode.net
(02:42:33 PM) DougieRichardson: and that we are going to be running IRC lessons, Playbooks, Doc Days and a new installation guide.
(02:42:47 PM) DougieRichardson: Lastly, please, please grab a copy of the playbook
(02:42:56 PM) DougieRichardson: http://www.lynxworks.eu/files/BugsPlaybook.pdf
(02:43:34 PM) DougieRichardson: We're always glas to accept new contributers and contributions, no matter how small - there is a very good chance that someone is looking for the information you have!
(02:44:05 PM) DougieRichardson: So I'll move on to Q&A - please, ask away!
(02:45:27 PM) DougieRichardson: Question: Hi Dinda, hopefully, given our new initiatives thats a yes but I think we need to integrate these ideas fully
(02:46:52 PM) dinda: QUESTION: The "Getting Involved" section of ubuntu.com points non-technical users who wan to contribute to the docs team.  Do you really think this is the right first place for new non-technical contributors?
(02:46:58 PM) dinda: repeating for the logs
(02:47:56 PM) dinda: QUESTION: Could you point us to the place to apply for membership in the doc team on Launchpad?
(02:48:23 PM) DougieRichardson: Answer: https://launchpad.net/ubuntu-doc
(02:49:16 PM) mfitzhugh: Not to be dumb, but I'm at that page and don't see a "join" link
(02:49:17 PM) dinda: QUESTION:  Can you explain the difference between the Core group and students group?
(02:50:39 PM) DougieRichardson: Apologies, it should have been https://launchpad.net/~ubuntu-doc
(02:51:43 PM) DougieRichardson: The team name for new contributers is still "students"
(02:51:57 PM) DougieRichardson: https://launchpad.net/~ubuntu-doc-students
(02:53:59 PM) dinda: dinda: QUESTION:  How many new contributors would you like to see coming on board each month?  release cycle?
(02:54:28 PM) DougieRichardson: Answer: I'd like to see as many as possible!
(02:54:54 PM) DougieRichardson: Answer: It depends in which area people would like to help.
(02:55:22 PM) DougieRichardson: QUESTION:  Is there a better time to jump into documentation?  i.e. the days before a release are prolly not the best
(02:55:22 PM) dinda: dinda: QUESTION:  Is there a better time to jump into documentation?  i.e. the days before a release are prolly not the best
(02:56:24 PM) DougieRichardson: Answer: Anytime is fine, as there's always bugs to fix but you're right - the start of the new development cycle is the ideal place because it allows more time to complete IRC training and improving our tool chain
(02:57:11 PM) mdke: so *now* is the ideal time!
(02:57:15 PM) DougieRichardson: But at the end of the release cycle we need as many eyes on as possible to check over the docs
(02:57:51 PM) DougieRichardson: Yes, like I said - please grab a playbook, join the team and we'll be happy to help
(03:00:07 PM) DougieRichardson: QUESTION: so, as I see students involved in bug-hunt process mostly?
(03:00:44 PM) DougieRichardson: Answer: No, we want to see students involved in fixing bugs, asking questions and making patches!
(03:01:23 PM) DougieRichardson: Bug hunting is very important - especially end of cycle but with six months in hand we've can cover our tool chain and bring students up to speed.
(03:01:59 PM) DougieRichardson: OK, I'm eating into mdke and adiroiban's time now so I'll finish off the Q&A
(03:02:18 PM) mdke: great job DougieRichardson
(03:02:25 PM) DougieRichardson: If anyone has any other question, you can contact the team or mail me direct through Launchpad.
(03:02:36 PM) dinda: Thanks Dougie - great job!
(03:02:47 PM) DougieRichardson: I'll finish with one link though: http://www.lynxworks.eu/files/BugsPlaybook.pdf