| === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu Documentation Day - Current Session: Introduction to Docs - Instructors: pleia2 | ||
| * pleia2 waves | 16:02 | |
| pleia2 | hello everyone :) bright and early here in California | 16:02 |
|---|---|---|
| pleia2 | (actually, not so bright, it's raining) | 16:03 |
| pleia2 | welcome to Ubuntu Documentation Day! We'll have 6.5 hours of sessions here in the Classroom about Ubuntu Documentation | 16:03 |
| pleia2 | if you're not already, you may join #ubuntu-classroom-chat as well to ask questions and chat with other attendees | 16:04 |
| pleia2 | questions should be in the form of: | 16:04 |
| pleia2 | QUESTION: Do you like Ubuntu? | 16:04 |
| pleia2 | so the ClassBot can pick them up :) | 16:04 |
| pleia2 | anyone want to give it a try? | 16:04 |
| ClassBot | knome asked: Is Xubuntu the best flavor? | 16:04 |
| pleia2 | haha, it depends on who you ask :) | 16:05 |
| ClassBot | belkinsa asked: What favor of Ubuntu is the best? | 16:05 |
| pleia2 | they're all wonderful! | 16:05 |
| pleia2 | alright, so that's questions | 16:05 |
| pleia2 | the schedule today is as follows: | 16:05 |
| pleia2 | 17:00 UTC Getting started contributing to Desktop docs with godbyk | 16:06 |
| pleia2 | 18:00 UTC Getting started contributing to Server docs with dsmythies | 16:06 |
| pleia2 | 19:00 UTC Getting started contributing to the Wiki docs with belkinsa | 16:06 |
| pleia2 | 20:00 UTC Getting started contributing to Manual with godbyk (again! busy guy) | 16:06 |
| pleia2 | 21:00 UTC Ubuntu Manual versions explained with tacorwin and patrickdickey | 16:07 |
| pleia2 | the full schedule is here, along with time zone conversions from UTC: https://wiki.ubuntu.com/DocumentationTeam/Classroom | 16:07 |
| pleia2 | now, this session is an introduction to docs, which shall serve as sort of a quick start to everything else that folks will be exploring today | 16:08 |
| pleia2 | I'll go through each of them quickly, syncing up with where they land on the schedule | 16:08 |
| pleia2 | feel free to ask questions, but anything complicated is probably best left for the person giving the session about that particular topic, since they're the experts :) | 16:08 |
| pleia2 | first up, Desktop docs! | 16:09 |
| pleia2 | the Desktop docs are shipped on every Ubuntu Desktop install | 16:09 |
| pleia2 | they're also published to help.ubuntu.com, so the latest official desktop docs can be found here: https://help.ubuntu.com/13.10/ubuntu-help/index.html | 16:10 |
| pleia2 | this makes them pretty important to get right, and since everyone who works on documentation in Ubuntu is an unpaid volunteer, we could always use the help with all aspects | 16:10 |
| pleia2 | the team commits to updating this documentation every cycle | 16:11 |
| pleia2 | on the technical side, the documentation is written in a markup language called "Mallard" (the same as what GNOME uses) and it lives at lp:ubuntu-docs which can be accessed via the revision control system bazaar (bzr) | 16:12 |
| pleia2 | godbyk will be giving the full tour in about 38 minutes | 16:12 |
| pleia2 | next up we have server documentation | 16:13 |
| pleia2 | this documentation is specific to servers running Ubuntu and is separate from the desktop documentation | 16:13 |
| pleia2 | just like desktop docs, the team is committed to releasing this every cycle | 16:14 |
| ClassBot | knome asked: Do flavors ship documentation, are they published online and do they also use Mallard and BZR? | 16:14 |
| pleia2 | many flavors do ship documentation, but they select the tools they use to write and publish, I'll get to that toward the end :) | 16:14 |
| pleia2 | unlike desktop docs, server docs are not shipped with installed versions of Ubuntu server and instead are just published on help.ubuntu.com | 16:15 |
| pleia2 | they're available there as html and pdf as you can see in the latest release here: https://help.ubuntu.com/13.10/index.html | 16:15 |
| pleia2 | these docs are written in DocBook, and are also available via bzr at lp:serverguide | 16:16 |
| pleia2 | DocBook is a pretty standard tool for writing documentation in open source projects, so many folks are already familiar with it | 16:16 |
| pleia2 | now, beyond these "official" documentation types in the core Docuemtation team, we also have docuementation that's maintained on the wiki | 16:18 |
| pleia2 | everything under /community at help.ubuntu.com is actually a wiki | 16:18 |
| pleia2 | starting here: https://help.ubuntu.com/community | 16:18 |
| pleia2 | this can be edited by anyone in the community, at any time, and there are no set deadlines or freezes for when it should be completed | 16:18 |
| pleia2 | as such, it's a much more "living" document that the community maintains, and while there is a team to keep an eye on things, it's not strictly updated every cycle | 16:19 |
| pleia2 | it's also not shipped with Ubuntu or anything, so it's more of an online reference | 16:20 |
| pleia2 | to get started working with this, all you need is a web browser and a launchpad account :) see here for getting started: https://wiki.ubuntu.com/DocumentationTeam/Wiki | 16:20 |
| pleia2 | wiki syntax is easier to learn than DocBook or Mallard, so a lot of folks enjoy starting here | 16:21 |
| pleia2 | ah, should clarify, a launchpad account linked to Ubuntu One account (if you sign up for launchpad today it's automatic, but if you have an older account it might not be), see: https://help.ubuntu.com/community/WikiGuide/Registration | 16:22 |
| pleia2 | the wiki also allows you to create new articles for things that aren't documented, and improve existing documents when you find errors, so it's a low barrier way to get involved | 16:23 |
| pleia2 | there's also the Ubuntu Manual project | 16:23 |
| pleia2 | the work the Ubuntu Manual does is to present a low-cost (or free pdf) printable Ubuntu book for users, their site is at http://ubuntu-manual.org/ | 16:23 |
| pleia2 | it's structured differently than the official desktop documentation because it's in book form, but the manual covers similar topics | 16:24 |
| pleia2 | the manual team has also been committed to releasing every cycle | 16:24 |
| pleia2 | the Manual is written in LaTeX and then exported to pdf and to online book print shops in whatever format they require | 16:25 |
| pleia2 | they also use bzr to track revisions | 16:26 |
| pleia2 | one of the things this team did early on was work to make it as easy as possible for contributors can help out, as you can see from their nice, clean get involved page: http://ubuntu-manual.org/getinvolved | 16:26 |
| pleia2 | so that's all the documentation that's focused on Ubuntu specifically - it's a lot! and we have a pretty small team for all of these | 16:27 |
| pleia2 | beyond that, some of the flavors of Ubuntu maintain their own documentation too | 16:28 |
| pleia2 | Xubuntu, for instance, has documentation that's written in DocBook and also lives on launchpad | 16:29 |
| ClassBot | ahoneybun asked: are other flavors of ubuntu going to talk? | 16:29 |
| pleia2 | unfortunately not! but from my experience xubuntu and kubuntu (the two that maintain docs) are friendly folks and can point you in the right direction | 16:30 |
| pleia2 | we'll work to get some flavor representatives in for our next Doc day :) | 16:31 |
| pleia2 | these documentation teams run pretty independently from Ubuntu, so they can choose their tools and publishing mechanisms | 16:31 |
| pleia2 | for Xubuntu the documentation is published on http://docs.xubuntu.org/ and shipped with each release | 16:32 |
| pleia2 | oh and xubuntu docs live on lp at lp:xubuntu-docs | 16:35 |
| pleia2 | and since we don't have a specific session for flavors, ahoneybun is here to give us some info about kubuntu documentation :) | 16:36 |
| ahoneybun | Hello all I am here for the Kubuntu Docs Team | 16:36 |
| ahoneybun | 'Docs" = Documentation | 16:36 |
| ahoneybun | Currently we have moved out docs over to http://userbase.kde.org/Kubuntu where you would need to log in here https://userbase.kde.org/index.php?title=Special:OpenIDLogin&returnto=Kubuntu | 16:37 |
| ahoneybun | It is based on MediaWiki vs MoinMoin that wiki.ubuntu.com uses | 16:38 |
| ahoneybun | Once we get the docs nice, perfect for release we export it into HTML then to DocBook for the khelpcenter to import | 16:39 |
| ahoneybun | we do use launchpad for a few things but not as much as say xubuntu at lp:kubuntu-docs | 16:40 |
| ahoneybun | and we have a docs website at http://docs.kubuntu.org/Kubuntu/KubuntuDocs.html but we are working on getting a way to create a snapshot at each release to push to that site | 16:41 |
| ahoneybun | Right now at http://userbase.kde.org/Kubuntu we need translators to make the docs the best and most available to everyone :) | 16:42 |
| pleia2 | thanks ahoneybun | 16:43 |
| ahoneybun | no problem :) | 16:43 |
| pleia2 | other flavors tend to either rely upon upstream, or have minimal documentation for specific tasks either on the wiki or on their website, like Edubuntu: https://edubuntu.org/documentation | 16:44 |
| pleia2 | so participating in upstream documentation is highly recommended as well :) | 16:44 |
| pleia2 | upstream == from projects that the distribution uses, like lxde or gnome | 16:45 |
| pleia2 | they also rely heavily (or exclusvely) on volunteers, so documentation everywhere always needs help from the community | 16:46 |
| pleia2 | finally, I also want to mention that the Ubuntu community also has wiki.ubuntu.com - which is not for user documentation, this tends to be confusing for a lot of people, it's actually a teams wiki that should be used by community members for project coordination and how-tos related to getting involved with their projects | 16:47 |
| pleia2 | and that's all I have for this whirlwind tour of documentation :) in 10 minutes or so we'll have godbyk give you a more in depth tour of the desktop docs, and again the full schedule is here: https://wiki.ubuntu.com/DocumentationTeam/Classroom | 16:49 |
| pleia2 | I was asked by dsmythies that if you are attending the server session later, that you install some packages with: | 16:49 |
| pleia2 | sudo apt-get install bzr docbook docbook-xsl xsltproc libxml2-utils yelp-tools yelp-xsl fop gnome-doc-utils make | 16:50 |
| ClassBot | There are 10 minutes remaining in the current session. | 16:50 |
| pleia2 | this will pull in what you need to contribute to server docs, and pulls in a bunch of dependencies so it'll take a few minutes | 16:51 |
| ClassBot | There are 5 minutes remaining in the current session. | 16:55 |
| ClassBot | gulundin asked: is some deadline set on the official documentation for the Trusty Tahr release? | 16:57 |
| pleia2 | great question, and there is! | 16:58 |
| pleia2 | grabbing the link for our release schedule | 16:58 |
| pleia2 | https://wiki.ubuntu.com/DocumentationTeam/ReleaseSchedule | 16:59 |
| pleia2 | DocumentationStringFreeze is coming up quick, on March 20th, so it needs to be done by then | 16:59 |
| === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu Documentation Day - Current Session: Getting started contributing to Desktop docs - Instructors: godbyk | ||
| ClassBot | Logs for this session will be available at http://irclogs.ubuntu.com/2014/03/02/%23ubuntu-classroom.html following the conclusion of the session. | 17:00 |
| godbyk | Hello, everyone, and welcome to the classroom session for Ubuntu desktop documentation. | 17:00 |
| godbyk | If you have any questions during this session, please ask in #ubuntu-classroom-chat. Don't forget to prefix your question with "QUESTION:" | 17:01 |
| godbyk | The upcoming sessions are: | 17:01 |
| godbyk | 18:00 UTC Getting started contributing to Server docs with dsmythies | 17:01 |
| godbyk | 19:00 UTC Getting started contributing to the Wiki docs with belkinsa | 17:01 |
| godbyk | 20:00 UTC Getting started contributing to Manual with godbyk | 17:01 |
| godbyk | 21:00 UTC Ubuntu Manual versions explained with tacorwin and patrickdickey | 17:01 |
| godbyk | As pleia2 mentioned in the previous session, the Ubuntu desktop docs are published each cycle along with Ubuntu. | 17:02 |
| godbyk | They are present in two places: | 17:02 |
| godbyk | 1. On your desktop (just search for 'help' in the Dash), and | 17:02 |
| godbyk | 2. Online at https://help.ubuntu.com/13.10/ubuntu-help/index.html. | 17:02 |
| godbyk | In this session, I'll give you a brief overview of how you can help contribute to the desktop documentation. | 17:03 |
| godbyk | For those of you who are eager to dive right in (and not wait on my slow typing!), you can follow our getting started guide at https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuDesktopGuide. | 17:04 |
| godbyk | To start working with the desktop documentation, you should first join our contributors team: https://launchpad.net/~ubuntu-doc-contributors | 17:05 |
| godbyk | And subscribe to our mailing list. | 17:05 |
| godbyk | You can help us by reviewing the current documentation online at https://help.ubuntu.com/13.10/ubuntu-help/index.html. | 17:05 |
| godbyk | If you find an error—incorrect information or typos—there are a few ways of correcting it: | 17:06 |
| godbyk | 1. Email the list. This is probably the easiest way as others will do most of the work. Just notifying us of these errors helps us enormously! | 17:07 |
| godbyk | 2. File a bug on Launchpad. You can file a bug against the ubuntu-docs project at https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs/+filebug. | 17:07 |
| godbyk | Be sure to include a link to the page you found the bug in and be specific about what the error is. | 17:08 |
| godbyk | 3. Create a patch and file a merge proposal. | 17:08 |
| godbyk | If you're feeling adventurous (and we hope you are!), you can download the documentation code yourself, fix the error, and submit a patch. | 17:08 |
| godbyk | After you've contributed to the project for a while, you can apply to become a "committer". | 17:09 |
| godbyk | Committers can commit code directly to the main bzr repository without having to create a merge proposal. | 17:09 |
| godbyk | They also help review and approve merge proposals from contributors. | 17:09 |
| godbyk | The Ubuntu desktop documentation is written in a markup language called Mallard. | 17:10 |
| godbyk | Mallard is designed specifically for topic-based documentation (as opposed to say, books or lengthier publications). | 17:10 |
| godbyk | En example Mallard document looks like this: http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-docs/trusty/view/head:/ubuntu-help/C/unity-launcher-intro.page | 17:11 |
| godbyk | When we convert this Mallard document to HTML, it looks like this: https://help.ubuntu.com/13.10/ubuntu-help/unity-launcher-intro.html | 17:11 |
| godbyk | If you search the Dash for 'help', it will bring up an offline viewer known as Yelp. | 17:11 |
| godbyk | Yelp can read and display Mallard pages directly without converting them to HTML first. | 17:11 |
| godbyk | Next, I'd like to walk you through the process of downloading our documentation source code. This process will also give you a head start on any server guide work you'd like to do. | 17:13 |
| godbyk | But first, are there any questions so far? | 17:13 |
| godbyk | Okay, let's dive in! If you have questions along the way, feel free to ask them in #ubuntu-classroom-chat. Don't forget to prefix your question with "QUESTION:". | 17:15 |
| godbyk | We've written a short guide to getting started with the desktop docs at <https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuDesktopGuide>. | 17:15 |
| godbyk | I'll be walking you through this process. | 17:15 |
| godbyk | !q | 17:16 |
| godbyk | jose: You can find out all about Mallard at http://projectmallard.org/. | 17:16 |
| ClassBot | jose asked: where can I learn Mallard? | 17:17 |
| godbyk | jose: We may not have time to cover much of Mallard in this sessions, but if there's interest, we could hold a future classroom session about it. | 17:17 |
| godbyk | Okay, for the first step, you'll need to install a few packages: | 17:19 |
| godbyk | $ sudo apt-get install bzr xsltproc libxml2-utils yelp-tools yelp-xsl | 17:19 |
| ClassBot | ahoneybun asked: how well does mallard handles translations? | 17:19 |
| godbyk | ahoneybun: Mallard handles translations pretty well. When we're finished updating the docs, we generate a translation template file and upload it to Launchpad. | 17:20 |
| godbyk | ahoneybun: Translators can then translate the documentation. The docs team will periodically upload the translations to the help.ubuntu.com website. | 17:21 |
| godbyk | Next, we'll need to generate an SSH key. | 17:21 |
| godbyk | First, check to see if you already have an SSH key: | 17:21 |
| godbyk | Open a terminal, and type: | 17:22 |
| godbyk | $ ls ~/.ssh/id_rsa.pub | 17:22 |
| godbyk | If it lists the file, then you already have an ssh key and can skip the next step. | 17:22 |
| godbyk | If you don't already have a key (it says "No such file or directory"), then we'll create one with the following command: | 17:23 |
| godbyk | $ ssh-keygen -t rsa | 17:23 |
| godbyk | It's easiest to just press Enter to accept the defaults to all of the questions. | 17:23 |
| godbyk | You may enter a password for additional security if you like, but it's not required. | 17:23 |
| ClassBot | jose asked: how do I open a terminal? | 17:24 |
| godbyk | jose: You can open a terminal by searching the Dash for 'Terminal' or by pressing Ctrl+Alt+T on your keyboard. | 17:24 |
| ClassBot | belkinsa asked: Is there a way to copy and paste those commands in the terminal for the ese? | 17:24 |
| godbyk | belkinsa: You can copy and paste these commands from the chat window or from our web page at https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuDesktopGuide. | 17:25 |
| godbyk | belkinsa: In your terminal, press Ctrl+Shift+V to paste the text. | 17:25 |
| godbyk | belkinsa: Be sure to leave out the initial $. That's just showing the prompt. | 17:25 |
| godbyk | Next, we'll need to upload the SSH key to Launchpad. | 17:26 |
| godbyk | Open your favorite web browser and head to https://launchpad.net/~/+editsshkeys | 17:26 |
| godbyk | If you don't yet have a Launchpad account, create one and then revisit the URL. | 17:27 |
| godbyk | If you already have a Launchpad account, log in. | 17:28 |
| godbyk | Scroll down to the bottom of the page and you'll see a large text box below the "Add an SSH key" heading. | 17:28 |
| godbyk | We'll need to paste the SSH key we just created into this box. | 17:29 |
| godbyk | In your terminal, run: | 17:29 |
| godbyk | $ gedit ~/.ssh/id_rsa.pub | 17:29 |
| godbyk | Copy the entire contents of this file and paste them into the textbox on the Launchpad page. Click the Import Public Key button. | 17:30 |
| godbyk | This SSH key allows us to communicate securely with Launchpad. | 17:30 |
| godbyk | Next, we'll set up bzr. | 17:30 |
| godbyk | bzr (Bazaar) is the version control system that Ubuntu uses for its projects. | 17:31 |
| godbyk | bzr maintains a history of all the changes we make to the documentation. | 17:31 |
| godbyk | This allows us to roll back any accidental changes and to see our progress as we update the documentation. | 17:31 |
| godbyk | First, we'll need to tell bzr who we are. | 17:32 |
| godbyk | We'll tell bzr which name and email address we'd like it to show when we submit code to Launchpad. | 17:32 |
| godbyk | Run the following command: | 17:33 |
| godbyk | $ bzr whoami "Kevin Godby <kevin@godby.org" | 17:33 |
| godbyk | Replace 'Kevin Godby' with your full name and 'kevin@godby.org' with your own email address. | 17:33 |
| godbyk | Don't forget the quotation marks. | 17:33 |
| godbyk | And don't forget to put your email address in < and > (like I failed to). | 17:33 |
| godbyk | $ bzr whoami "Kevin Godby <kevin@godby.org>" | 17:33 |
| godbyk | Next, we'll need to tell bzr what our Launchpad username is: | 17:34 |
| godbyk | $ bzr launchpad-login godbyk | 17:34 |
| godbyk | If you've forgotten your Launchpad username, you can find it by visiting https://launchpad.net/~ in your web browser. | 17:34 |
| godbyk | Launchpad will redirect you to your Launchpad account page. The part of the address after the tilde (~) is your username. | 17:35 |
| godbyk | Finally, we can download a copy of the documentation using bzr. | 17:35 |
| godbyk | This step can take a little bit of time because we're downloading the entire history of all of the changes made to the documentation over the years. | 17:35 |
| godbyk | In your terminal, run the following command: | 17:36 |
| godbyk | $ bzr branch lp:ubuntu-docs | 17:36 |
| godbyk | Are there any questions so far? | 17:37 |
| godbyk | Since it will take a little while to download the documentation, we'll explore the files online. | 17:39 |
| godbyk | If you visit http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-docs/trusty/files with your web browser, you can see a list of all of the files and directories in the bzr repository. | 17:39 |
| godbyk | These are the files that are being downloaded by bzr. | 17:39 |
| godbyk | The Mallard files that we write for the desktop documentation live in the ubuntu-help/C/ subdirectory. | 17:40 |
| godbyk | Click on ubuntu-help and then C to find .page files. | 17:40 |
| godbyk | The .page files contain the Mallard markup for the documentation. | 17:41 |
| godbyk | Let's take another look at the example Mallard file I showed you earlier: http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-docs/trusty/view/head:/ubuntu-help/C/unity-launcher-intro.page | 17:42 |
| godbyk | Once bzr has finished downloading all the files, you can open this file on your computer by running the following command in your terminal: | 17:42 |
| godbyk | $ gedit ubuntu-docs/ubuntu-help/C/unity-launcher-intro.page | 17:43 |
| godbyk | If you spot an error in this file, you have a few options for correcting it: | 17:43 |
| godbyk | 1. Email the ubuntu-docs mailing list about it and someone there will fix it. | 17:44 |
| godbyk | 2. File a bug report at https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs/+filebug and someone there will fix it. | 17:44 |
| godbyk | 3. Make the changes yourself. | 17:45 |
| godbyk | The first two options are fairly self-explanatory, so let's explore the third option. | 17:45 |
| godbyk | You can open the offending .page file in gedit, make the desired changes, and save the file. | 17:45 |
| godbyk | Now you have the corrected .page file on your own computer. | 17:45 |
| godbyk | The next step is to get your changes back to Launchpad so they can be incorporated into the main documentation repository. | 17:46 |
| godbyk | First, you'll need to commit your changes to the bzr repository. | 17:47 |
| godbyk | Run the following command: | 17:47 |
| godbyk | $ cd ~/ubuntu-docs | 17:47 |
| godbyk | $ bzr commit -m 'A brief description of your changes goes here' | 17:47 |
| godbyk | The 'bzr commit' command will commit your changes. The text between the apostrophes should be a short description of the changes you've made. | 17:48 |
| godbyk | Next, you'll need to upload your changes to Launchpad. | 17:48 |
| godbyk | Run the following command: | 17:48 |
| godbyk | $ bzr push lp:~username/ubuntu/trusty/ubuntu-doc/my-first-change | 17:49 |
| godbyk | where you've replaced 'username' with your own username and 'my-first-change' with a couple words describing your change (no spaces allowed). | 17:49 |
| ClassBot | There are 10 minutes remaining in the current session. | 17:50 |
| godbyk | Finally, you'll need to create a 'merge proposal' to alert the ubuntu-docs team of your proposed changes so they can be reviewed. | 17:50 |
| godbyk | Run: | 17:50 |
| godbyk | $ bzr lp-propose | 17:50 |
| godbyk | This command will open your web browser to the merge proposal page on Launchpad. Provide a brief description of your proposed changes and submit the merge proposal. | 17:51 |
| godbyk | The ubuntu-docs team will be notified of your merge proposal. | 17:51 |
| godbyk | They will review your proposed changes and either accept them or discuss them with you. | 17:51 |
| godbyk | We've only had a short time to get an overview of the Ubuntu desktop documentation and how you can join the team. | 17:52 |
| godbyk | If you'd like more information, feel free to email us on our mailing list at ubuntu-doc@lists.ubuntu.com or chat with us in our IRC channel at #ubuntu-doc. | 17:53 |
| godbyk | We hope to hear from you soon! | 17:53 |
| godbyk | We have a few minutes for some questions. | 17:53 |
| godbyk | In our next session, dsmythies will discuss the server documentation. | 17:54 |
| ClassBot | There are 5 minutes remaining in the current session. | 17:55 |
| dsmythies | to help save time in the sererguide session please do this (if you didn't already), as it might take over 15 minutes: | 17:58 |
| dsmythies | $ sudo apt-get install bzr docbook docbook-xsl xsltproc libxml2-utils yelp-tools yelp-xsl fop gnome-doc-utils make | 17:58 |
| === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu Documentation Day - Current Session: Getting started contributing to Server docs - Instructors: dsmythies | ||
| ClassBot | Logs for this session will be available at http://irclogs.ubuntu.com/2014/03/02/%23ubuntu-classroom.html following the conclusion of the session. | 18:00 |
| dsmythies | Hello everyone, my name is Doug Smythies and this is the "Getting Started Contributing to the Serverguide" session. | 18:00 |
| dsmythies | Over the next hour, and for the Ubuntu Serverguide, we will learn: How to setup a working environment; How to build and verify the HTML and PDF versions; How to create and submit a merge proposal. | 18:00 |
| dsmythies | Note that I am IRC challenged, and have asked for help from invisbile to you classroom volunteers, whom I would like to thank now, because I will forget at the end. | 18:00 |
| dsmythies | Could everybody participating please comment in #ubuntu-classroom-chat. And please say if you intend to "participate" or just follow along but not actually "do", as the numbers will dictate how I deliever the material. | 18:01 |
| dsmythies | Questions are O.K. during this session, but I might not see them right away. Please ask in #ubuntu-classroom-chat. Be sure to prefix it with 'QUESTION:' to ensure that it gets noticed by the classroom robot. | 18:02 |
| dsmythies | Prerequisites: You should already have a launchpad account, with an uploaded ssh key for the computer you will be using. You should already have bzr installed and setup. Is this O.K or is it a problem for anyone? | 18:03 |
| dsmythies | Hmmm.... | 18:04 |
| dsmythies | I guess I'll move along then... | 18:05 |
| dsmythies | We will work on 3 real bug reports, but don't worry they are simple typo bug reports. At this stage we are here to learn about the process and not get lost in some detailed overhaul of a chapter or section. | 18:06 |
| dsmythies | While what we are covering shouldn't take too long, there might be download delays and such which could result in time pressures for the hour. | 18:06 |
| dsmythies | First and foremost, we should always have the serverguide "quick how to" page open somewhere on our desktop and as our main reference. | 18:07 |
| dsmythies | Please open: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuServerGuide | 18:07 |
| dsmythies | and go to the kickstart section. | 18:07 |
| dsmythies | Second, things are done via the command line, so we always need some sort of terminal window or session open. Go ahead and make a terminal window or open an ssh session now. | 18:07 |
| dsmythies | Cut and paste the install the software line (even if you think you already have everything installed, there is no harm in checking): | 18:08 |
| dsmythies | Note: Lyz asked you to do this earlier and I asked awhile ago also. | 18:09 |
| dsmythies | $ sudo apt-get install bzr docbook docbook-xsl xsltproc libxml2-utils yelp-tools yelp-xsl fop gnome-doc-utils make | 18:09 |
| dsmythies | This step might take 15 minutes or more, if you do not already have anything installed. | 18:10 |
| dsmythies | (I am hoping you have done this already, as pleia2 mentioned the command at the end of her session. Although I know some of you might not have been here then.) | 18:10 |
| dsmythies | O.K.? comment on #ubuntu-classroom-chat as to progress. And note that even if you took Kevin's session just prior to this one, there are an extra couple of packages needed for Serverguide. | 18:10 |
| dsmythies | Now we are ready to get a local copy of the master files for the Ubuntu Servverguide: | 18:13 |
| dsmythies | 1.) make a working directory and change to it: | 18:13 |
| dsmythies | $ mkdir sguide-1404 | 18:13 |
| dsmythies | $ cd squide-1404 | 18:13 |
| dsmythies | 2.) make a local copy (branch) of the master Serverguide files: (put it in the subdirectory called "classroom")(this will take at least 4 minutes.) | 18:14 |
| dsmythies | $ bzr branch lp:serverguide classroom | 18:14 |
| dsmythies | If it is your first bzr/launchpad interaction, you will see: | 18:15 |
| dsmythies | The authenticity of host 'bazaar.launchpad.net (91.189.95.84)' can't be established. | 18:15 |
| dsmythies | RSA key fingerprint is bla bla bla. | 18:15 |
| dsmythies | Are you sure you want to continue connecting (yes/no)? | 18:15 |
| dsmythies | enter "yes" | 18:15 |
| dsmythies | This step might take 4 minutes or more. | 18:15 |
| dsmythies | O.K.? comment on #ubuntu-classroom-chat as to progress. | 18:16 |
| dsmythies | 3.) Now, before we make any changes, check to make sure everything is O.K..That the code builds and that the code validates: | 18:17 |
| dsmythies | $ cd classroom | 18:18 |
| dsmythies | $ scripts/validate.sh serverguide/C/serverguide.xml | 18:18 |
| dsmythies | $ make serverguide-html | 18:18 |
| dsmythies | $ make serverguide-pdf | 18:18 |
| dsmythies | While we have worked hard to get rid of exranious messages during compile, there are still a few. | 18:20 |
| dsmythies | Now have a look at the compiled serverguide. How you actually do this will depend on your setup. I do things on a server and have the drive shared with my Laptop via Samba. If you are using a desktop computer you can use it directly. | 18:20 |
| dsmythies | The built serverguide will be in the build/serverguide/C sub-directory. Navegate there and open the index.html file. Similarly for the serverguide.pdf file. In both the HTML and the PDF, browse to the Zyntal section. | 18:21 |
| dsmythies | Note: in the new (Red) theme, sometimes it is not obvious where stuff is in the HTML. With the old (Brown) theme it was easier. (It is under "Remote administration") | 18:21 |
| dsmythies | If you are just following along and not actually building on your local machine, then go to https://help.ubuntu.com/13.10/index.html and proceed from there. | 18:22 |
| dsmythies | TIP: Sometimes it is easier to find stuff in the .PDF because you can search the whole document, and then you know where to look in the HTML. | 18:22 |
| dsmythies | Once we have determined that the unaltered code validates and compiles, we are ready to start making changes. | 18:23 |
| dsmythies | Let's look at the first bug report we intend to tackle: Please all open a new broswer page and go to bug 1278146 | 18:23 |
| dsmythies | https://bugs.launchpad.net/serverguide/+bug/1278146 | 18:24 |
| dsmythies | O.K.? comment on #ubuntu-classroom-chat that you have opened and read the bug report. | 18:24 |
| dsmythies | I'll set the bug report status to "In progress". I already assigned myself so as to hold the bug report for this class, but typically you would assign yourself, or maybe you were previously assigned. | 18:25 |
| dsmythies | I want everybody to click and add themselves to get every e-mail about this bug report (over on the right about 4 or 5 groups down). | 18:25 |
| dsmythies | First we check our compiled HTML and PDF, so we can verify before and after we fix it. Search for "a serie of" | 18:26 |
| dsmythies | Now, we have the context of the bug report. This will be useful later. | 18:28 |
| dsmythies | Close the PDF Serverguide, because (at least on my computer) we can not rebuild it while it is open. Keep the HTML open. | 18:28 |
| dsmythies | Now we have to figure out where the referenced error is in the source code. (ignoring for the moment, that I already did that and made an entry in the bug report.): | 18:28 |
| dsmythies | $ cd serverguide | 18:29 |
| dsmythies | $ cd C | 18:29 |
| dsmythies | $ grep -n "a serie of" *.xml | 18:29 |
| dsmythies | you should get this: | 18:29 |
| dsmythies | remote-administration.xml:451: <application>Zentyal</application> consists of a serie of packages | 18:29 |
| dsmythies | So you know line 451 of remote-administration.xml is the line to fix. | 18:29 |
| dsmythies | O.K.? Was everyone able to identify the issue in the source code? | 18:30 |
| dsmythies | TIP: Sometimes our grep search fails. Why? Because sometimes there are line breaks in the source code that interfere with the search pattern. If that happens, just move the search pattern a little. | 18:30 |
| dsmythies | TIP: Notice that in the HTML "Zyntal" is in italics. That likley means that it is surrounded by docbook tags in the source code, and we should not include it in the grep search pattern. | 18:30 |
| dsmythies | We are ready to make a change to the source code. Use your preferred editor to open remote-administration.xml and go to line 451, make the required change and save the file. I use nano. | 18:31 |
| dsmythies | O.K.? We'll wait for everybody. (I'm dropping the "comment on #ubuntu-classroom-chat" from here on, assuming you know to. (nobody seems to be doing this anyhow)) | 18:33 |
| dsmythies | moving on... | 18:34 |
| dsmythies | Always, always validate: | 18:34 |
| dsmythies | $ cd .. | 18:34 |
| dsmythies | $ cd .. | 18:34 |
| dsmythies | $ scripts/validate.sh serverguide/C/serverguide.xml | 18:34 |
| dsmythies | $ make serverguide-html | 18:34 |
| dsmythies | $ make serverguide-pdf | 18:35 |
| dsmythies | And refresh your browser and observe the fixed code. Open the serverguide.pdf file, and observe there also. | 18:35 |
| dsmythies | Let's do some bzr checks: | 18:35 |
| dsmythies | $ bzr status | 18:35 |
| dsmythies | $ bzr diff | 18:35 |
| dsmythies | aghhh... I see that someone did add themselves to the bug report. Great. | 18:36 |
| dsmythies | So onto the second bug, one submitted by a translator. bug 1272984 . Flaipe always submits very nice typo bugs with a reference to the source file and line. However, often reports from translators only contain the string reference, and you'll have to figure it out for yourself. | 18:37 |
| dsmythies | https://bugs.launchpad.net/serverguide/+bug/1272984 | 18:37 |
| dsmythies | The process is the same as the last one. Add your names to be notified about changes to this bug report. | 18:39 |
| dsmythies | Find the typo in the HTML and PDF documents. | 18:39 |
| dsmythies | (Hint try the TIP from earlier and find it in the PDF first.) | 18:39 |
| dsmythies | Ugh Oh.... I have a confusing note in my script. What on earth was I thinking? .... | 18:40 |
| dsmythies | $ grep -n repostory serverguide/C/*.xml | 18:41 |
| dsmythies | $ serverguide/C/vcs.xml:199: <para>Or add the server's project as a remote for an existing git repostory:</para> | 18:41 |
| dsmythies | $ nano serverguide/C/vcs.xml (you use whatever editor you prefer) | 18:41 |
| dsmythies | Always, always validate: | 18:43 |
| dsmythies | $ scripts/validate.sh serverguide/C/serverguide.xml | 18:43 |
| dsmythies | $ make serverguide-html | 18:43 |
| dsmythies | $ make serverguide-pdf | 18:43 |
| dsmythies | And refresh your browser and observe the fixed code. Open the serverguide.pdf file, and observe there also. | 18:44 |
| dsmythies | Again, let's do some bzr checks: | 18:44 |
| dsmythies | $ bzr status | 18:44 |
| dsmythies | $ bzr diff | 18:44 |
| dsmythies | One more, another one from Flaipe: bug 1272064 | 18:45 |
| dsmythies | https://bugs.launchpad.net/serverguide/+bug/1272064 | 18:45 |
| dsmythies | Go ahead and do this one yoursleves, without any input from me. (However note that when I sreached the PDF for "the the", I found some other occurances. Normally we would stop and fix those also, but we don't have time right now.) | 18:46 |
| dsmythies | ... I am doing it also ... | 18:48 |
| dsmythies | O.K.? Is everybody done? | 18:49 |
| dsmythies | Did everyone do the bzr checks as the last step? and does everyone get this: http://paste.ubuntu.com/7023049/ | 18:49 |
| dsmythies | Now it is time to wrap this up and put our branch into launchpad. Starting with a commit line. Use the wiki page as a reference. (and use your name and your launchpad account name): | 18:50 |
| ClassBot | There are 10 minutes remaining in the current session. | 18:50 |
| dsmythies | $ bzr commit --fixes lp:1278146 --fixes lp:1272984 --fixes lp:1272064 -m 'simple typos; LP: #1278146; LP: #1272984; LP: #1272064; by Doug Smythies' | 18:50 |
| dsmythies | $ bzr push lp:~dsmythies/serverguide/classroom | 18:52 |
| dsmythies | this is taking ahile and I might run out of time... | 18:53 |
| dsmythies | You should also be getting e-mails from the bug reports saying that branches are linked to them. | 18:53 |
| dsmythies | Now go to your launchpad account under the "code tab" and you should see your code there. Click on it to go there. | 18:53 |
| dsmythies | You should see the bug reports under "Related bugs" with links to them. | 18:53 |
| dsmythies | Under recent revisions you should see your just uploaded revision. Click on the revision number, 188. | 18:53 |
| dsmythies | ... my upload is taking awhile... I'll add my remaining notes here and we'll come back to this is there is time. | 18:55 |
| ClassBot | There are 5 minutes remaining in the current session. | 18:55 |
| dsmythies | Click on each of the modified files listed to expand the color differences. Do they make sense? (they should). | 18:55 |
| dsmythies | Go back to branch summary, either via the link in the top left corner or via the browser back button. | 18:55 |
| dsmythies | Under "Branch merges" clcik on "Propose for merging" | 18:55 |
| dsmythies | Enter a description. "Simple typos" will do in this case | 18:56 |
| dsmythies | Leave blank the spots where it says "optional", they will autofill with the correct information. | 18:56 |
| dsmythies | Click on the "Propose Merge" radio button at the bottom of the page. | 18:56 |
| dsmythies | After a short delay you should see a Merge Proposal page with a MP number. | 18:56 |
| dsmythies | I'll add a comment and "approve" and then also set the status to "approve" | 18:57 |
| dsmythies | I go to my up to date working branch, and merge in the MP: | 18:57 |
| dsmythies | $ bzr merge lp:~jdoe/serverguide/classroom | 18:57 |
| dsmythies | $ bzr commit --fixes lp:1278146 --fixes lp:1272984 --fixes lp:1272064 -m 'simple typos per MP: #XXXXXX; LP: #1278146; LP: #1272984; LP: #1272064; by Jane Doe' | 18:57 |
| dsmythies | $ bzr push lp:serverguide | 18:57 |
| dsmythies | Notice the MP automatically got set to a status of "merged" | 18:57 |
| dsmythies | ( or woul dhave if we actually did this part) | 18:58 |
| dsmythies | We should also now set the bug reports status' to "fix committed". (which I will complete after the class.) | 18:58 |
| dsmythies | ... my upload continues... I shdould have done one before and had it ready. Sorry. | 18:59 |
| === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu Documentation Day - Current Session: Getting started contributing to the Wiki docs - Instructors: belkinsa | ||
| belkinsa | Thank you, dsmythies, for your session. I hope that helps everyone who wants to help out. | 19:00 |
| dsmythies | The class will switch over in a moment. Thanks. | 19:00 |
| ClassBot | Logs for this session will be available at http://irclogs.ubuntu.com/2014/03/02/%23ubuntu-classroom.html following the conclusion of the session. | 19:00 |
| belkinsa | Hey all from snowy Southwest Ohio, welcome to the, "Getting started contributing to the Wiki docs", session. My name is Svetlana Belkin (A.K.A. belkinsa) and I'm your instructor. | 19:00 |
| belkinsa | If you have any questions during this session, please ask in #ubuntu-classroom-chat. Don't forget to prefix your question with "QUESTION:" | 19:01 |
| belkinsa | The upcoming sessions are: | 19:01 |
| belkinsa | 20:00 UTC Getting started contributing to Manual with godbyk | 19:01 |
| belkinsa | 21:00 UTC Ubuntu Manual versions explained with tacorwin and patrickdickey | 19:01 |
| belkinsa | Before I start with my lesson: If you'd like more information, feel free to email us on our mailing list at ubuntu-doc@lists.ubuntu.com or chat with us in our IRC channel at #ubuntu-doc. Please use the prefixes: [Desktop],[Server], and [Wiki] when you mail the list. Each of them are for the three types of docs that we have. | 19:01 |
| belkinsa | Like what pleia2 said about the Wiki. We have two types of wikis: the wiki.ubuntu.com where our teams hold pages, and for you the ones who are active and wish to seek the Ubuntu Membership. The Community Help Wiki contains all of the support pages that don't go into our guides that we have. | 19:03 |
| belkinsa | The link to the Community Help Wiki is: https://help.ubuntu.com/community | 19:03 |
| belkinsa | The great thing about the Community Help Wiki is that anyone with a LaunchPad account can edit pages and there is no fear of doing anything wrong since we have wiki admins that approve the changes and the rollback feature. | 19:05 |
| belkinsa | How to get a Launchpad Account? Here is how: https://help.ubuntu.com/community/WikiGuide/Registration | 19:05 |
| belkinsa | Any questions? | 19:05 |
| belkinsa | Okay, our example that will be used is that you all (those who wants to learn how to wiki edit) will be creating your every own Userpage that you can use to show when you apply to the Ubuntu Membership. | 19:07 |
| belkinsa | To do this, first you need to log into the wiki by going to wiki.ubuntu.com. | 19:08 |
| belkinsa | You should see a Ubuntu logo banner and below it, a menu bar that says "Log in" or "edit", if you are logged in. | 19:09 |
| belkinsa | If you are not logged in, please click that "Log in" and proceeded to log in with your LaunchPad account. | 19:09 |
| ClassBot | jose asked: Do both wikis use moinmoin? | 19:09 |
| belkinsa | Yes, both do. | 19:10 |
| belkinsa | MoinMoin is a wiki syntax that both wikis use and it's easy to learn. | 19:10 |
| belkinsa | This link has the syntaxes: https://help.ubuntu.com/community/WikiGuide/Formatting | 19:11 |
| belkinsa | Okay, once you are logged in. Go to this page: https://wiki.ubuntu.com/MembershipTemplate | 19:12 |
| belkinsa | This page contains the template that we will use. | 19:12 |
| belkinsa | There are two ways to copy and paste this template into a new page. | 19:12 |
| belkinsa | The first one is to "Edit" the page. You do this by hitting "edit" on the menu bar under the Ubuntu banner and it should take you to a text editor with the text for the template. Copy that. | 19:13 |
| belkinsa | Or you can go to the drop down menu and select "copy". This should take you a page that says where to copy the page. | 19:14 |
| belkinsa | I think the first method is the easiest. | 19:14 |
| belkinsa | Because you need to know where to copy the page. | 19:15 |
| belkinsa | In the address bar: type in https://wiki.ubuntu.com/<username>. <useraname> is your username that you use in LaunchPad. | 19:15 |
| belkinsa | Thanks, jose. Don't use edit to view the source, use the drop down and select 'view raw' | 19:16 |
| belkinsa | This is for the first method. ^^^ | 19:16 |
| belkinsa | Once you are at your page, you should see a dialogue telling you that it is not created yet. Click "create a new page". This should take you to the editor. | 19:17 |
| belkinsa | At the editor, paste the template. There is a menu above the editor. Select "preview" and it will show you what you have done or you can select "Save" and the page will be saved and you should see a normal looking page without the editor. | 19:19 |
| belkinsa | Any questions? | 19:19 |
| belkinsa | Oh, as an example: https://wiki.ubuntu.com/belkinsa This is my page, please use "view raw" to see what I have done. | 19:20 |
| belkinsa | You can write anything about yourself. ;) | 19:21 |
| belkinsa | Okay, now you have the basics of the syntax and how to edit a page. | 19:21 |
| belkinsa | Now, when you find a page to work on, you can do it right on that page or you can use a page called a "sandbox" page. | 19:22 |
| belkinsa | These sandboxes are used to play around with pages with out effecting the main one. | 19:23 |
| belkinsa | To create one, the easiest way to https://wiki.ubuntu.com/<username>/sandbox ( <useraname> is your username that you use in LaunchPad). Follow the directions as for your userpage to create a blank page to fill. | 19:24 |
| belkinsa | You can add more pages after the first one by https://wiki.ubuntu.com/<username>/sandbox/<newpage>. | 19:25 |
| belkinsa | As with all pages, don't forget to save when you are done and preview to extend the lock period. | 19:26 |
| belkinsa | Any questions so far? | 19:26 |
| belkinsa | There is a way to see what other users did to the pages and these are called "revisions". | 19:28 |
| belkinsa | These allow rollbacking to older versions of pages. | 19:29 |
| belkinsa | Log in which is under the “Ubuntu Wiki” banner. Under the “Ubuntu Wiki”, you should see a menu bar that starts with “Edit” | 19:29 |
| belkinsa | Next to the 'Edit”, you should see a “Info” button- this will take you to a page called Revision History | 19:29 |
| belkinsa | Here you can see: | 19:29 |
| belkinsa | Revision Number (#) - which shows how many revisions the page gone through | 19:30 |
| belkinsa | Date – which shows when the revision was made | 19:30 |
| belkinsa | Size – which shows how large the page and/or if there is attachments to the page | 19:30 |
| belkinsa | Duff - which allows to compare two versions of the same page | 19:30 |
| belkinsa | Editor – which allows to see who done the last edit | 19:30 |
| belkinsa | Comment – which allows to see what the editor did, if there is a comment | 19:30 |
| belkinsa | Action – which allows to view the page without the diff | 19:30 |
| belkinsa | Clicking on “View” will allow to enter the revision. | 19:30 |
| belkinsa | If you want to rollback: | 19:31 |
| belkinsa | Go back to the menu bar under the Ubuntu Wiki banner and find the drop down that is labeled, “More Actions:”. | 19:31 |
| belkinsa | Scroll down to “Revert to this revision”. | 19:31 |
| belkinsa | Another page will pop up after section | 19:31 |
| belkinsa | You can comment on why you doing this | 19:31 |
| belkinsa | And select “Revert” if you are sure on the choice | 19:31 |
| belkinsa | Any questions on revisions? | 19:31 |
| belkinsa | Before I forget about creating new pages: https://help.ubuntu.com/community/WikiGuide/PageCreation. This page contains a temple if you want to create a new page: https://help.ubuntu.com/community/DocumentationTemplate | 19:33 |
| belkinsa | If you don't have any expertise on any subject, the Doc team has small tasks for people to do. These range from proofreading to tagging pages. | 19:34 |
| belkinsa | https://wiki.ubuntu.com/DocumentationTeam/Wiki/Tasks | 19:35 |
| belkinsa | Has the tasks. | 19:35 |
| belkinsa | We also have a tagging system to tag pages: , https://help.ubuntu.com/community/Tag These tags help us to figure out what needs to be deleted or needs fixing. | 19:36 |
| belkinsa | We might have a Global Jam session(s) for this this year, if we have people wanting to help to clean up the wiki. | 19:37 |
| belkinsa | Any questions before I move on? | 19:37 |
| belkinsa | Okay. | 19:39 |
| belkinsa | The wiki has a way to categorize pages in order for the pages of the same subject mater to stay together. | 19:40 |
| belkinsa | he format is CategoryCategory where the second is the name of the category | 19:40 |
| belkinsa | The* | 19:40 |
| belkinsa | This must be placed on the bottom of the page with “----” before it in one line. | 19:41 |
| belkinsa | iii. https://help.ubuntu.com/community/CategoryCategory has more information | 19:41 |
| belkinsa | minus iii. | 19:41 |
| belkinsa | This could be a focus for someone who has expertise on a subject matter so they can review many pages in one place. | 19:42 |
| belkinsa | Any questions? | 19:43 |
| belkinsa | My final topic for my lesson is the other projects that people can do with us. | 19:45 |
| belkinsa | The first is the importing "How To Do" guides from the Ubuntu Forums: https://wiki.ubuntu.com/DocumentationTeam/Wiki/Tasks/Forum | 19:45 |
| belkinsa | The Ubuntu Forums have a wealth of information available. It is important to ensure that the wiki documentation (and ultimately the documentation which is included in the Ubuntu system) benefits from that information. | 19:46 |
| belkinsa | Same rules for these pages created apply. | 19:46 |
| belkinsa | The other project is the PopularDocs project. | 19:47 |
| belkinsa | https://launchpad.net/~newdocs | 19:47 |
| belkinsa | This project is now under the Doc Team and we aim to index the most used pages in order for users to find what they need faster. | 19:47 |
| belkinsa | We == as in the team. I'm a part of it. | 19:48 |
| belkinsa | Any questions for my final section? | 19:49 |
| ClassBot | There are 10 minutes remaining in the current session. | 19:50 |
| belkinsa | As I said before, the wiki is a great place to start with the Doc team since it has less of a barrier and it's easier to understand. | 19:50 |
| belkinsa | As always: | 19:51 |
| belkinsa | If you'd like more information, feel free to email us on our mailing list at ubuntu-doc@lists.ubuntu.com or chat with us in our IRC channel at #ubuntu-doc. Please use the prefixes: [Desktop],[Server], and [Wiki] when you mail the list. Each of them are for the three types of docs that we have. | 19:51 |
| belkinsa | I would like to thank everyone who came and did the example as I was teaching it. Hopefully this can help you leap into wiki editing and hopefully get you to help us to have a useful wiki for all. | 19:52 |
| belkinsa | I would like to also thank pleia2 and the rest for planning this Classroom session/Doc Day event. | 19:53 |
| belkinsa | It was fun teaching this session. | 19:53 |
| pleia2 | thanks belkinsa! | 19:53 |
| belkinsa | In five (5) minutes, godbyk will be teaching his "Getting started contributing to Manual" lesson. | 19:55 |
| ClassBot | There are 5 minutes remaining in the current session. | 19:55 |
| ClassBot | knome asked: Should I be worried about messing something up in the wiki? | 19:58 |
| belkinsa | knome, no, because of the rollback feature and the wiki admins are aways there. | 19:59 |
| belkinsa | The wiki admins are users with more power than the normal user. | 19:59 |
| belkinsa | They can delete and rename pages. | 19:59 |
| === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu Documentation Day - Current Session: Getting started contributing to Manual - Instructors: godbyk | ||
| ClassBot | Logs for this session will be available at http://irclogs.ubuntu.com/2014/03/02/%23ubuntu-classroom.html following the conclusion of the session. | 20:00 |
| godbyk | Welcome to the Ubuntu Manual classroom session. | 20:00 |
| godbyk | The Ubuntu Manual Project publishes "Getting Started with Ubuntu" every six months. | 20:01 |
| godbyk | "Getting Started with Ubuntu" is a beginner's guide for Ubuntu. It's aimed at helping those who are new to Ubuntu become familiar with it. | 20:01 |
| godbyk | You can download a free PDF of the book from our website at http://ubuntu-manual.org/. | 20:02 |
| godbyk | You can also purchase a printed and bound copy through CreateSpace.com or Amazon.com. | 20:02 |
| godbyk | If you have any questions during this session, feel free to ask them in #ubuntu-classroom-chat. Don't forget to prefix your question with "QUESTION:". | 20:03 |
| godbyk | The Ubuntu manual covers a lot of material that's helpful for new users. | 20:03 |
| godbyk | It walks the reader through installing Ubuntu, introduces the Ubuntu desktop, instructs on how to install software, explains how to set up common applications, and provides some troubleshooting information. | 20:04 |
| godbyk | The manual is written and edited by a team of volunteers. | 20:05 |
| godbyk | We're always looking for more authors and editors to help us out. | 20:05 |
| godbyk | This session will explain how you can start contributing to the Ubuntu manual. | 20:05 |
| godbyk | There are a number of ways you can help create the next Ubuntu manual: | 20:06 |
| godbyk | * You can become an author. | 20:06 |
| godbyk | Authors help write new material to cover new Ubuntu applications and features. | 20:06 |
| godbyk | They also update the existing text when Ubuntu changes with each release. | 20:07 |
| godbyk | * You can become an editor. | 20:07 |
| godbyk | Editors review what the authors have written. | 20:07 |
| godbyk | The editors proofread the text for grammatical and spelling errors. They also ensure the information is accurate and up to date. | 20:07 |
| godbyk | * You can become a translator. | 20:08 |
| godbyk | We would like to publish the manual in as many languages as we can. | 20:08 |
| godbyk | The manual is currently available in English, Spanish, German, Dutch, Greek, Lithuanian, and Slovenian. | 20:09 |
| godbyk | If you'd like to get involved in the Ubuntu Manual Project, you can find more information on our website at http://ubuntu-manual.org/getinvolved. | 20:11 |
| godbyk | In this session, I'll briefly walk you through part of the process of becoming and author/editor and a translator. | 20:12 |
| godbyk | 1. Becoming an author or editor | 20:12 |
| godbyk | The complete instructions and process for becoming an author or editor are outlined online at http://ubuntu-manual.org/getinvolved/authors | 20:12 |
| godbyk | The first step is to create a Launchpad account and join our team. | 20:13 |
| godbyk | If you don't already have a Launchpad account, you can create one for free at https://launchpad.net/ | 20:13 |
| godbyk | Once you've registered an account, you can join our team by visiting https://launchpad.net/~ubuntu-manual/ and clicking "Join this team". | 20:13 |
| godbyk | While you're there, subscribe to our mailing list. | 20:14 |
| godbyk | As an author or editor, you'll be working directly with our documentation files. | 20:15 |
| godbyk | We write our documentation using a markup language called LaTeX. | 20:15 |
| godbyk | We'll explore the LaTeX markup language a bit later in this session. | 20:15 |
| godbyk | Now that you have a Launchpad account and you've joined our team, you can download our documentation files. | 20:16 |
| godbyk | If you haven't already done so, you'll need to generate an SSH key and share it with Launchpad before you can download the files. | 20:16 |
| godbyk | To create an SSH key, open a terminal (by searching for 'Terminal' in the Dash or pressing Ctrl+Alt+T on your keyboard), and type the following commands (ignoring the $): | 20:17 |
| godbyk | $ sudo apt-get install openssh-client | 20:17 |
| godbyk | $ ssh-keygen -t rsa | 20:17 |
| godbyk | You can just press Enter to accept the default answers to all of the questions that ssh-keygen asks you. | 20:18 |
| godbyk | You may specify a password if you like, but it's not necessary. | 20:18 |
| godbyk | ssh-keygen will create a file named id_rsa.pub in the .ssh/ subdirectory of your home directory. | 20:18 |
| godbyk | We'll need to upload the the contents of this file to Launchpad. | 20:19 |
| godbyk | Visit your SSH keys page at https://launchpad.net/people/+me/+editsshkeys | 20:19 |
| godbyk | Open your key file by running the following command in a terminal: | 20:19 |
| godbyk | $ gedit ~/.ssh/id_rsa.pub | 20:19 |
| godbyk | Copy the contents of that file to your clipboard and paste it into the text box at the bottom of the Launchpad page. Click the "Import public key" button to continue. | 20:20 |
| godbyk | Now we can start downloading the documentation files. | 20:20 |
| godbyk | Install Bazaar by running the following command: | 20:20 |
| godbyk | $ sudo apt-get install bzr | 20:21 |
| godbyk | Tell bzr who you are: | 20:21 |
| godbyk | $ bzr whoami "Your name <email@domain.com>" | 20:21 |
| godbyk | Change 'Your name' to your own full name and 'email@domain.com' to your email address. Don't forget to include the quotation marks and the angle brackets. | 20:21 |
| godbyk | Give bzr your Launchpad username: | 20:22 |
| godbyk | $ bzr launchpad-login myusername | 20:22 |
| godbyk | You can find your username by visiting http://launchpad.net/~ | 20:22 |
| godbyk | Launchpad will display your username after the tilde (~) in the address bar. | 20:22 |
| godbyk | Finally, we can start downloading the documentation files: | 20:23 |
| godbyk | $ bzr branch lp:ubuntu-manual | 20:23 |
| godbyk | This may take a few minutes depending on the speed of your Internet connection. | 20:23 |
| godbyk | Once you've finished downloading the documentation files, you can start taking a look at them. | 20:24 |
| godbyk | For this session, we'll explore the files online. | 20:24 |
| godbyk | Due to time constraints, I've omitted some of the steps required for you to build the manual PDF yourself. For full instructions, please visit http://ubuntu-manual.org/getinvolved/authors | 20:25 |
| godbyk | Inside the ubuntu-manual directory, you'll see a number of subdirectories and files. You can view these online at http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/trusty/files | 20:26 |
| godbyk | Each chapter of the manual is stored in its own subdirectory (e.g., installation, ubuntu-desktop, learning-more). | 20:26 |
| godbyk | Let's take a look at the installation chapter. | 20:26 |
| godbyk | Inside the installation/ subdirectory, you'll find an installation.tex file. | 20:27 |
| godbyk | The .tex files are the LaTeX source files for our manual. | 20:27 |
| godbyk | You can view the installation.tex file online at http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/trusty/view/head:/installation/installation.tex | 20:27 |
| godbyk | While the LaTeX markup may appear daunting at first, it's fairly simple to read and use once you get accustomed to it. | 20:28 |
| godbyk | We won't have time in this session to explore the LaTeX markup language, but you can find more information about how we use LaTeX in our style guide. | 20:28 |
| godbyk | Our style guide is available online at http://files.ubuntu-manual.org/style-guide.pdf | 20:28 |
| godbyk | The style guide covers most of what you'll need to know to participate in the Ubuntu Manual Project: | 20:29 |
| godbyk | * how to become a member of the project | 20:29 |
| godbyk | * the setup instructions we're coving in this session (and more) | 20:29 |
| godbyk | * how we use bzr | 20:29 |
| godbyk | * how we use the LaTeX markup language | 20:30 |
| godbyk | * information for translators | 20:30 |
| godbyk | * usage notes on terminology used in the manual | 20:30 |
| godbyk | Back to the installation.tex file (http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/trusty/view/head:/installation/installation.tex) | 20:30 |
| godbyk | If you compare the contents of that file to the contents of the Installation chapter in the PDF of our manual (available at http://ubuntu-manual.org//download/13.10/en_US/screen), | 20:31 |
| godbyk | you'll see how the markup language handles all of the formatting for us. | 20:31 |
| godbyk | For example, we just specify a section heading and LaTeX will decide how to style it (font size, bold, etc.). | 20:32 |
| godbyk | Are there any questions about anything we've covered so far? | 20:32 |
| godbyk | If you decide you'd like to become an author or editor, please send an email to our mailing list at ubuntu-manual@lists.launchpad.net and we'll help you get started. | 20:33 |
| godbyk | You'll be able to choose which section of the manual you'd like to work on. | 20:33 |
| godbyk | Okay, next, we'll see how our manual is translated into various languages. | 20:34 |
| godbyk | As I mentioned before, our manual is translated into a number of languages. | 20:34 |
| godbyk | If you'd like to help with one of the existing languages or translate the manual into a new language, just let us know! | 20:35 |
| godbyk | Instructions for translators are available online at http://ubuntu-manual.org/getinvolved/translators and in our style guide (available at http://files.ubuntu-manual.org/style-guide.pdf). | 20:35 |
| godbyk | Becoming a translator is pretty easy. | 20:36 |
| godbyk | The first step is to create a Launchpad account if you don't already have one. | 20:36 |
| godbyk | We covered that in detail earlier. | 20:36 |
| godbyk | Once you've created an account, go to your page: launchpad.net/~ | 20:36 |
| godbyk | Click on the yellow 'edit' icon next to the Languages header and add all the language you speak. | 20:37 |
| godbyk | Some translation teams require you join their team before you can translate text into that language. | 20:37 |
| godbyk | For those teams, you'll need to visit their team page on Launchpad and sign up to join their team. Each team may have its own requirements for joining. | 20:38 |
| godbyk | Finally, you can visit our translations page at http://translations.launchpad.net/ubuntu-manual. | 20:38 |
| godbyk | You should see your preferred languages listed. Click on the language you'd like to translate to and start translating the text. | 20:38 |
| godbyk | As a translator, you will need to learn a bit about the LaTeX markup language to know what parts of the text you should and shouldn't translate. | 20:39 |
| godbyk | You can find all the details of this in chapter 7 of our style (again, available at http://files.ubuntu-manual.org/style-guide.pdf). | 20:39 |
| godbyk | If you have any questions about translating that aren't answered by our style guide, feel free to ask on the ubuntu-manual mailing list or in the #ubuntu-manual channel here on IRC. | 20:40 |
| godbyk | Are there any questions about translating the Ubuntu manual? | 20:40 |
| godbyk | All right, if there are any other questions about the Ubuntu Manual project or any of the other Ubuntu docs projects, feel free to ask them in #ubuntu-classroom-chat. | 20:45 |
| godbyk | Don't forget to prefix your question with "QUESTION:". | 20:45 |
| ClassBot | benonsoftware asked: Is the Ubuntu Manual in the Ubuntu archive? | 20:46 |
| godbyk | benonsoftware: The manual isn't currently available in the Ubuntu archive or the Software Center. | 20:46 |
| godbyk | You can download a PDF of the manual for free from our website at http://ubuntu-manual.org/downloads | 20:47 |
| godbyk | Or you can purchase printed-and-bound copies of the book online at http://ubuntu-manual.org/buy/gswu1310/en_US or through Amazon.com. | 20:47 |
| ClassBot | belkinsa asked: Wouldn't be better to use the content from Ubuntu Desktop guide in the Ubuntu Manual? | 20:47 |
| godbyk | belkinsa: The manual covers many of the same topics as the desktop docs do, but it's in a different form. | 20:48 |
| godbyk | The desktop docs are written in a topic-based way. They're designed to answer an immediate 'how do I...?' question. | 20:48 |
| godbyk | The manual is designed to be something that you could sit down and read through as you learn Ubuntu. | 20:49 |
| godbyk | The manual is also useful if you don't have access to the Internet or haven't yet installed Ubuntu to be able to access the desktop docs. | 20:49 |
| ClassBot | There are 10 minutes remaining in the current session. | 20:50 |
| godbyk | By the way, if you don't want to commit to becoming an author, editor, or translator, you can still help improve the Ubuntu manual by emailing feedback@ubuntu-manual.org with suggestions for how we can improve the manual. | 20:51 |
| godbyk | If you found a typo, incorrect or outdated information, or have a suggestion for a topic we should write about, feel free to email us. | 20:51 |
| ClassBot | jsjgruber-l101-p asked: Does the printed manual come with an Ubuntu CD? | 20:51 |
| godbyk | jsjgruber-l101-p: The printed manual doesn't come with an Ubuntu CD at this time. | 20:52 |
| godbyk | It's a good idea, though, and something we'd love to be able to do in the future! | 20:52 |
| godbyk | Are there any other questions about the Ubuntu manual or any of the other Ubuntu docs projects? | 20:52 |
| godbyk | In a few minutes, the next session will start: Ubuntu Manual versions explained by tacorwin. | 20:55 |
| ClassBot | There are 5 minutes remaining in the current session. | 20:55 |
| === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu Documentation Day - Current Session: Ubuntu Manual versions explained - Instructors: tacorwin, patrickdickey | ||
| ClassBot | Logs for this session will be available at http://irclogs.ubuntu.com/2014/03/02/%23ubuntu-classroom.html following the conclusion of the session. | 21:00 |
| tacorwin | Hello everyone! Before we start, I'd like to mention that there will be three sections in this session: The Ubuntu Manual, the Lubuntu Manual, and a proposed project, the Wine on Ubuntu Manual project. | 21:00 |
| tacorwin | Please save all questions until the end of each section, respectively. | 21:01 |
| tacorwin | Since godbyk has explained the Ubuntu Manual, I won't go in depth, but rather skim the topic. | 21:01 |
| tacorwin | The Ubuntu Manual project was created in 2009 by Benjamin Humphrey to provide up-to-date information for new users of the Ubuntu OS. | 21:02 |
| tacorwin | We try to make every ounce of information educational an simple to understand to lower the Linux barrier for new users. | 21:03 |
| tacorwin | There are many ways to contribute to the manual: Becoming an author, editor, translator, designer, etc. | 21:04 |
| tacorwin | I will be skipping the "how to contribute" portion, as it was previously explained. | 21:04 |
| tacorwin | As I said, this was brief. | 21:05 |
| tacorwin | Any questions pertaining to the Ubuntu Manual? | 21:05 |
| tacorwin | Okay. The next topic is the Lubuntu Manual Project. | 21:06 |
| tacorwin | The Lubuntu Manual was just created last year to provide the same form of documentation for the Lubuntu variant. | 21:07 |
| tacorwin | The contribution types are the same (Author, Editor, etc.), but things are a bit shaky at the moment, as they are trying to start the actual work of the first manual release. | 21:08 |
| tacorwin | To contribute, follow this link. https://wiki.ubuntu.com/Lubuntu/DocumentationTeam/Manual | 21:09 |
| tacorwin | There is a Launchpad project for the Lubuntu Manual as well, that you should add to become part of the team. | 21:09 |
| tacorwin | You can simply join Lubuntu Wiki and Docs Team and after the administrator of the team approve your request, please send an introduction email to the list and make yourself known. | 21:10 |
| tacorwin | This will ensure that your efforts are known to all members. | 21:10 |
| tacorwin | You should also add your name to the list on the page (referring to the last link). | 21:11 |
| tacorwin | There really aren't a whole lot of details I can give at this point about the LMP, because they have recently started up, and haven't entirely started releasing a manual. | 21:12 |
| tacorwin | If there are any specific questions about this manual, you can ask now. | 21:13 |
| tacorwin | We have one more topic to cover, the Wine on Ubuntu Manual Project. | 21:15 |
| tacorwin | I can give more information on this manual, unlike the others because I have proposed it and have (slowly) started the production of it. | 21:16 |
| tacorwin | In a nutshell, the WOUMP (abbr.) is an attempt to lower the Linux barrier even more by explaining how to run a lot of Windows programs on a Linux OS (Ubuntu) using WINE (Wine Is Not an Emulator) | 21:18 |
| tacorwin | This manual was proposed about 6 months ago, by myself, and will hopefully be adapted as an official Ubuntu Manual Project affiliate. | 21:19 |
| ClassBot | There are 10 minutes remaining in the current session. | 21:20 |
| tacorwin | Right now, contributors are needed to start the project in the right direction, but I will explain what will be contained. | 21:20 |
| tacorwin | Installation, configuration, usage, and uninstallation are just a few of the topics planned to be in the manual. | 21:21 |
| tacorwin | For a list of plausible sections, go to: https://docs.google.com/spreadsheet/ccc?key=0ApexI9z0UYtGdERqWHpEZmpXVUgwZV9CeExFdlNBT0E&usp=docslist_api | 21:23 |
| tacorwin | This is a spreadsheet containing the old authors and editors list I was going to uses | 21:23 |
| tacorwin | I will use the last few minutes to answer specific questions about this manual, as well as any others mentioned previously. | 21:23 |
| ClassBot | There are 5 minutes remaining in the current session. | 21:25 |
| ClassBot | belkinsa asked: How many are in the WINE Manual team at the moment? | 21:25 |
| tacorwin | One, unfortunately. | 21:26 |
| tacorwin | I'm currently trying to find other contributors. | 21:26 |
| tacorwin | belkinsa: forgot to put your name. :P | 21:27 |
| ClassBot | belkinsa asked: Have you done anything to promote it? | 21:27 |
| tacorwin | belkinsa: not exactly. I wanted to further organize it before I began a full-scale team. | 21:28 |
| tacorwin | Any other questions? :) | 21:28 |
| ClassBot | Logs for this session will be available at http://irclogs.ubuntu.com/2014/03/02/%23ubuntu-classroom.html | 21:30 |
| pleia2 | thanks tacorwin! | 21:30 |
| tacorwin | This was the last session for today's Documentation Day. Thank you all for attending. | 21:30 |
| === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || No Sessions Currently in Progress | ||
| tacorwin | :) anytime pleia2 | 21:30 |
Generated by irclog2html.py 2.7 by Marius Gedminas - find it at mg.pov.lt!