[04:00] <humphreybc> um
[04:00] <humphreybc> i have a voice!
[04:00] <humphreybc> [SLIDE 1]
[04:01] <humphreybc> https://wiki.ubuntu.com/ubuntu-manual
[04:01] <humphreybc> Can i have a show of hands for who's actually here?
[04:02] <humphreybc> we'll wait another 2 minutes for some stragglers to arrive
[04:04] <humphreybc> okay so those who aren't using Lernid, you can get the slides from  http://kevin.godby.org/ubuntu-manual/talks/
[04:04] <humphreybc> Also, you can chat in #ubuntu-classroom-chat
[04:04] <humphreybc> because you're not voiced in this chatroom
[04:05] <humphreybc> and lastly, to use the ClassBot question feature, ask a question in the chatroom and preface it with "QUESTION"
[04:05] <humphreybc> eg, "question: why are you telling me all this even though I already know it?"
[04:05] <humphreybc> i'm going to assume everyone's happy and i'll move on!
[04:05] <humphreybc> you can ask a question whenever you want btw
[04:06] <humphreybc> okay so, the ubuntu manual project
[04:06] <humphreybc> what the project is about. [SLIDE 2]
[04:06] <humphreybc> what we're trying to do is create some great documentation that's easy to follow and all in one place
[04:07] <humphreybc> I used to be an Ubuntu beginner once
[04:07] <humphreybc> and basically when I started I found the help to be quite hard to find, our out dated
[04:07] <humphreybc> that's nothing against the docs team, they're doing the best they can and it's hard to maintain docs
[04:08] <humphreybc> so what we're trying to do is create an up-to-date comprehensive manual that's in a context for fairly new people to Ubuntu and computers in general
[04:08] <humphreybc> We'll re-release a version every 6 months to coincide with Ubuntu releases
[04:08] <humphreybc> at the moment we're obviously working on the Lucid release
[04:09] <humphreybc> The project itself only started a couple of months ago with just me writing the document myself. I originally was going to make it closed-source but free, 50 pages or so, not a huge amount of screenshots, in open office and only in english
[04:09] <humphreybc> but some ubuntu community members advised me to open it for collaboration on launchpad
[04:09] <humphreybc> So i did
[04:09] <humphreybc> turned out that a lot of people felt that a manual like this was really needed
[04:10] <humphreybc> so now we have 250+ contributors, working towards a 200 page manual with 50 screenshots translated into 40+ languages
[04:10] <humphreybc> instead of using open office we write it using latex
[04:10] <humphreybc> [SLIDE 3]
[04:10] <humphreybc> Who it's for
[04:11] <humphreybc> We're targeting people who have possibly used a computer before on either Windows or Mac
[04:11] <humphreybc> we expect them to know what a mouse is and we expect them to have basic computer skills - enough to be able to acquire the manual in the first place
[04:11] <humphreybc> but from then on, our manual is written assuming they've never heard of Ubuntu or Linux
[04:11] <humphreybc> so we give an introduction to Ubuntu/Linux, history of it, talk about the community and FOSS software etc in the prologue
[04:12] <humphreybc> we teach them everything they need to know to get stuff done
[04:12] <humphreybc> but we don't teach them too much
[04:12] <humphreybc> our target audience view computers as a "means to an end"
[04:12] <humphreybc> they don't want to know how it works, they just want to know how to get stuff done, like print or send emails or view photos :)
[04:13] <humphreybc> [SLIDE 4]
[04:13] <humphreybc> So basically What we want to achieve - i've sort of covered this already
[04:13] <humphreybc> our goals are inclusion on the default CD at some stage, and definitely in the repositories.
[04:13] <humphreybc> we want to give the reader many choices with regards to language, format, layout, paper size etc
[04:14] <humphreybc> so in the future we're planning an HTML5 version, paper sizes will be attached to languages (en_US will be US Letter size, en_GB will be A4 etc)
[04:15] <humphreybc> and we're going to create a nice website with an easy way to acquire the right manual. probably just three questions that they answer, like "what language do you speak" "what country are you from" and "what distribution would you like the manual for"
[04:15] <humphreybc> (we might do a Kubuntu/Xubuntu/Ubuntu Netbook Edition/Ubuntu Developers Manual etc down the line, depending on the success of this one)
[04:15] <humphreybc> okay, so, any questions on all of that before I move on?
[04:16] <humphreybc> (questions can be asked in #ubuntu-classroom-chat)
[04:16] <humphreybc> nope?
[04:16] <humphreybc> okay, moving on
[04:16] <humphreybc> [SLIDE 5]
[04:17] <humphreybc> so that's all well and good I hear you say, but _how_ is all this going to happen?
[04:17] <humphreybc> well, we are using a bunch of existing tools and creating our own tools in some instances
[04:18] <humphreybc> basically the manual itself is written using LaTeX 2009, in .tex files that are compiled into a PDF (and down the line, other formats like HTML5)
[04:18] <humphreybc> we use Launchpad for blueprints, code hosting, milestones, bugs, answers and translations
[04:18] <humphreybc> We use Bazaar for version control, and the Ground Control application as a GUI front end to bzr
[04:19] <humphreybc> We use Launchpad's rosetta system for translations, and po4a to take the strings out of the .tex files and put them into .po and .pot files
[04:19] <humphreybc> we use several methods of communication, namely, IRC channel (#ubuntu-manual), mailing list, wiki, weekly meetings, facebook, msn, skype
[04:19] <humphreybc> we also have an aggregated blog: http://planet.interesting.co.nz
[04:20] <humphreybc> We thrive on publicity and hype, and we have ambitious goals
[04:20] <humphreybc> but we have a fast paced development environment
[04:20] <humphreybc> there isn't much stuffing around, we just "get things done."
[04:20] <humphreybc> [SLIDE 6]
[04:21] <humphreybc> Who the key people are
[04:21] <humphreybc> I won't repeat what's on the slide here because you should be able to see it
[04:21] <humphreybc> basically there are 6 key people
[04:21] <ClassBot> vdquynh asked: on which server is the #ubuntu-manual channel (I'm connected and searching irc.ubuntu.com)
[04:21] <humphreybc> irc.freenode.net :)
[04:22] <humphreybc> sorry I should have made that clear
[04:22] <humphreybc> so 6 key people, myself, project leader, dutchie who does a tonne of backend stuff, godbyk who does the latex stuff, Ilya, who works with the authors, Jamin who coordinates editing and thorwil who does the artwork
[04:23] <humphreybc> we also have a small team of developers working on Quickshot (i'll explain what Quickshot is soon)
[04:23] <humphreybc> by the way, these slides are all available in our bzr branch lp:ubuntu-manual
[04:23] <humphreybc> [SLIDE 7]
[04:23] <humphreybc> Okay, Quickshot!
[04:23] <humphreybc> So, basically, in our manual we have around 50 spaces for where we'd like to put screenshots
[04:24] <humphreybc> and we want all the screenshots to be localized (no use putting an english screenshot in the chinese manual)
[04:24] <humphreybc> so, 40 translations
[04:24] <humphreybc> the math is 50 x 40 = 2000 screenshots
[04:24] <humphreybc> we also need the resolution, theme, applications, dpi, file format, file name etc to be consistent so we can work well with them in LaTeX, and also so it looks good
[04:25] <humphreybc> it would take years for a few people to get all these shots themselves, and it would be very very inefficient and time consuming
[04:25] <humphreybc> so i came up with the idea to write a program that automates a lot of the stuff
[04:26] <humphreybc> quickshot isn't really a screenshotting application - that's what it does, yes, but it's only a small part. the big part of quickshot is that it sets up a new default user with the default theme, switches users to that user, pulls a branch full of some code that tells it what screenshots need to be taken. Quickshot then tells the user what screenshot they'll be taking, tells them to set up their screen, takes the shot and 
[04:26] <humphreybc> the UI looks like this at the moment: [SLIDE 8]
[04:27] <humphreybc> For the technical peeps: it's written in Python using Quickly and Glade to design the UI
[04:27] <humphreybc> [SLIDE 9]
[04:27] <humphreybc> Okay, so, how you can help us!
[04:27] <humphreybc> What's cool about our project is:
[04:28] <humphreybc> 1. We cover a huge range of stuff, from programming to writing, to editing and artwork, to maintaining social sites and updating twitter. you name it, we do it.
[04:28] <humphreybc> 2. We are fast paced, we're fun to work with, and there are always things happening
[04:28] <humphreybc> 3. We run a lot of events and we do a lot of cool stuff
[04:29] <humphreybc> and 4. We make it easy for you to join and get started
[04:29] <humphreybc> So, questions?
[04:30] <humphreybc> no one has any questions at all?
[04:30] <humphreybc> yay!
[04:30] <ClassBot> vdquynh asked: Is Quickshot ready to be used right now?
[04:30] <humphreybc> Nope, it's not. It's still under heavy development - I only thought of the idea last week :P
[04:30] <humphreybc> you can check out the branch though, http://launchpad.net/quickshot
[04:30] <humphreybc> bzr branch lp:quickshot
[04:31] <humphreybc> you can run it by double clicking the run.sh script
[04:31] <humphreybc> TommyBrunn is working on the Python with ubuntujenkins, i'm helping with the UI and bzr stuff
[04:31] <humphreybc> and yes, we do need help!
[04:32] <humphreybc> that's okay
[04:32] <humphreybc> when it's finished it will be super dooper easy to use :P
[04:32] <humphreybc> abeisgreat, meh, i'm not very good at python either
[04:32] <humphreybc> any help would be useful, honestly
[04:33] <ClassBot> epkugelmass_lern asked: How are discussions progressing with the Ubuntu distro drivers? Are they actively considering Ubuntu Manual for 10.04 release? I know the feature freeze (a3) is coming up fast.
[04:33] <humphreybc> No, they're not. It won't be in the Lucid CD because a) Lucid is an LTS b) we're a very young project and c) we weren't at UDS-L to actually suggest it
[04:33] <humphreybc> but don't worry, it will be easily accessible on websites/repos etc
[04:33] <humphreybc> and i'll put it forward for 10.10 :)
[04:33] <humphreybc> should be on the CD for 10.10
[04:34] <ClassBot> Takyoji asked: Where would it be listing of what exact screenshots need to be taken? Also, is it on a basis of a person being assigned to taking screenshots of the same dialog in different languages, or?
[04:34] <humphreybc> What's happening is the authors are inserting a command into their latex chapters where they think a screenshot is necessary. in the compiled PDF it looks like "MISSING SCREENSHOT" and has a description underneath
[04:34] <humphreybc> these missing screenshots are actually exported to a file in the branch "screenshots.log" i think
[04:35] <humphreybc> that list will be taken, with some nifty scripting, and duplicated for 40 different branches, one for each language
[04:35] <humphreybc> inside each branch will be folders for chapter, and in each chapter will be the relevant screenshots as plain text files containing their description. Quickshot will be programmed to find plain text files and treat them as "screenshots that are yet to be taken"
[04:36] <humphreybc> it will pull the description out, and, when the shot is taken, replace the plain text file with an image file ending in .png
[04:36] <humphreybc> Quickshot will then ignore .png files as they've already been done :)
[04:36] <humphreybc> We are aiming to get this thing ready for the Ubuntu Global Jam
[04:36] <humphreybc> so we can get tonnes of people screenshotting
[04:37] <humphreybc> oh also, Quickshot will have the ability to change the system language for the "quickshot" user
[04:37] <humphreybc> obviously all the english screenshots will be captured first
[04:37] <humphreybc> so once that's done, we'll have to have the user switch to another language for taking shots :)
[04:37] <humphreybc> good question.
[04:38] <humphreybc> https://wiki.ubuntu.com/ubuntu-manual/quickshot
[04:39] <ClassBot> Abeisgreat asked: How far along is quickshot? I know you said it's only a week old, but how far is it?
[04:40] <humphreybc> surprisingly we're doing pretty well
[04:40] <humphreybc> I've finished most of the main UI dialogs
[04:40] <humphreybc> Quickshot at the moment can:
[04:40] <humphreybc> Create a new user
[04:40] <humphreybc> Prompts the current user to switch (and has a button to do that)
[04:40] <humphreybc> opens on start in the quickshot user
[04:40] <humphreybc> account
[04:40] <humphreybc> it can also remove that user
[04:41] <humphreybc> next on the list is creating the bzr branch, pulling it and installing dependencies like language packs and fonts if they want to change language
[04:41] <humphreybc> we're aiming for it to be ready by March 18th (manual beta, lucid beta)
[04:41] <humphreybc> and then finished bug-free by April 1st
[04:41] <humphreybc> That gives us about a month of solid screenshotting till our RC on the 20th of April
[04:42] <humphreybc> we'll start the english screenshots on March 4th which is the Lucid UI freeze
[04:42] <humphreybc> and we are going to use those as "example" shots
[04:42] <humphreybc> it's all very busy
[04:43] <humphreybc> yep, it's a cool project
[04:43] <humphreybc> I really like quickshot, it's a bit of fun
[04:43] <ClassBot> Takyoji asked: What if the default theme in Lucid is changed?
[04:43] <humphreybc> the default theme is changing in Lucid :)
[04:44] <humphreybc> we're packaging Quickshot actually for Lucid, and targeting it at Lucid testers
[04:44] <humphreybc> and after March 4th, Lucid won't and can't change in appearance at all because that's the User Interface freeze
[04:44] <humphreybc> we don't have much time, so we'll need all the help we can get
[04:44] <humphreybc> and we're designing quickshot to be as easy and automated as humanly possible
[04:44] <humphreybc> so even your grandma should be able to capture screenshots for us!
[04:45] <ClassBot> vdquynh asked: How will we interact with bzr? Will it be sufficient to have a Launchpad account?
[04:46] <humphreybc> Yes, the branch will be entirely open so anyone with an lp account should have write permissions and auto-merging. We are considering seeing if the launchpad guys can actually make our branch public so _anyone_ (even without an lp account) can push. Either that, or ask them to sign in on Quickshot and if they don't have an account, create one through Quickshot
[04:46] <ClassBot> Takyoji asked: Would that imply that March 4th would be a reasonable time to start helping with taking screenshots? (or whenever the new theme is officially released)
[04:46] <humphreybc> Not much will be happening around March 4th, but on March 18th there will be a huge rush as all hands man the screenshot pumps!
[04:47] <humphreybc> We're aiming to get everything out of the way in the project before march 18th - that means writing, content, editing, icons, title page, artwork, style, colours... everything
[04:47] <humphreybc> March 18th is our writing freeze so translations can catch up
[04:47] <humphreybc> so all of our team will be screenshotting for a whole month
[04:47] <humphreybc> :)
[04:48] <ClassBot> vdquynh asked: Do I understand well that translations shoud better start after March 18th?
[04:49] <humphreybc> yep, at the moment translations are a bit hay-wire. I wasn't even planning on having anything more than an english manual, so I never thought about translations. Then all of a sudden we had like 100 people from all countries start emailing us asking for translation support, so we rushed to build it in
[04:49] <humphreybc> the problem with translating stuff early is that it is subject to change
[04:49] <humphreybc> and so a lot of the stuff they're translating is changing every day as authors and editors re-work sections and bits and pieces
[04:50] <humphreybc> I would wait until March 18th to start translating, because then you know anything you do will stick as our writing is frozen. Anything in the manual on March 18th is there for good, no exceptions. (unless some cheeky blighter drops in a swear word somewhere right before the freeze)
[04:51] <humphreybc> yup :)
[04:51] <humphreybc> more questions? we've still got 10 minutes until i start rambling on about ground control and how cool it is :)
[04:53] <humphreybc> cool :)
[04:55] <humphreybc> http://launchpad.net/groundcontrol
[04:59] <ClassBot> Takyoji asked: What will be the licensing of the Ubuntu Manual?
[04:59] <humphreybc> Creative Commons Attribution Share Alike :)
[05:00] <humphreybc> which basically means that it's free, anyone can use the source code, copy it, change it, redistribute it etc
[05:00] <humphreybc> okay, ground control!
[05:00] <humphreybc> [SLIDE 1]
[05:00] <humphreybc> once again, slides available @ http://kevin.godby.org/ubuntu-manual/talks/
[05:01] <humphreybc> or if you're using Lernid, you should see them to the top right!
[05:01] <humphreybc> So, Ground Control is basically a front end to bzr/bazaar
[05:01] <humphreybc> it's a python plugin for Nautilus written by Martin Owens
[05:01] <humphreybc> it's pretty sweet, avoids the command line entirely and makes stuff a lot simpler
[05:01] <humphreybc> it's not perfect yet, but it does the job and martin needs more testers so I offered to use it in UMP
[05:02] <humphreybc> soooo for you to install it and run it, i've made a handy dandy walkthrough video
[05:02]  * humphreybc tries to find the link
[05:02] <humphreybc> http://www.youtube.com/watch?v=MeNXqfofbWk
[05:02] <humphreybc> it should appear in Lernid
[05:03] <humphreybc> so have a watch of that
[05:03] <humphreybc> it's just over 6 minutes long
[05:03] <humphreybc> and let me know when you've watched it :)
[05:05] <humphreybc> [SLIDE 2]
[05:05] <humphreybc> I just put the commands in the slideshow window
[05:08] <humphreybc> okay so everyone watched it?
[05:08] <humphreybc> please say something so i know there are still people here...
[05:08] <humphreybc> okay cool we can wait, we've got tonnes of time
[05:09] <humphreybc> groovy, ok we'll move on but i'll leave the video there
[05:10] <humphreybc> [SLIDE 3]
[05:10] <humphreybc> so basically, as you can see from the video it's pretty easy to use
[05:10] <humphreybc> where some people had difficulty earlier today was with setting up the SSH key when logging into your account
[05:10] <humphreybc> so let me know if that's a problem for anyone
[05:11] <humphreybc> basically just the most important thing is to a) make sure you're a member of our team
[05:11] <humphreybc> and b) check the "download my branch" radio button
[05:11] <humphreybc> if you choose either of the other two, you'll end up with a read only branch that you can't commit, or you'll push and create a merge proposal. We avoid merge proposals, and i'll tell you why
[05:12] <humphreybc> other projects that are crucial to the system, such as the boot team stuff, software center, synaptic etc
[05:12] <humphreybc> they use merges because they don't want someone coming along and deleting all the code or stuffing it up and then pushing to main
[05:12] <humphreybc> so they review each merge and approve or decline it for inclusion into main
[05:12] <humphreybc> why don't we do that? easy:
[05:13] <humphreybc> 1. We have so many people committing and making revisions, we'd have merge proposals coming out of our easr
[05:13] <humphreybc> ears*
[05:13] <humphreybc> 2. We don't have time to bother with merge reviews because we're too busy working on the project - we have a tight enough schedule as it is without a full time merge reviewer!
[05:13] <humphreybc> But you may say "well what happens if someone breaks something?" - we can easily revert to an earlier revision
[05:14] <humphreybc> in this case, not having merges has more benefits for us than cons
[05:14] <humphreybc> so, that's why you "download my branch" so you can push directly into main
[05:14] <humphreybc> remember the requirements to be able to get our branch. You need:
[05:14] <humphreybc> 1. A launchpad account
[05:14] <humphreybc> 2. An SSH key for your computer
[05:14] <humphreybc> 3. To be a member of our team
[05:14] <humphreybc> 4. Have bzr or Ground Control installed
[05:15] <humphreybc> [SLIDE  4]
[05:15] <humphreybc> [SLIDE 5]
[05:15] <humphreybc> wait
[05:15] <humphreybc> [SLIDE 4]
[05:15] <humphreybc> there we go :P
[05:15] <humphreybc> Okay so you probably don't need to know this but I think it's quite cool so i'm going to tell you
[05:15] <humphreybc> at the end of the video you might have noticed some buttons that say "Make Show" and "Make Clean"
[05:16] <humphreybc> vdquynh: good question, i'll have to find out. hang on, i'll answer that in a sec :)
[05:16] <humphreybc> okay so these developer buttons are a feature in Ground Control 1.5
[05:17] <humphreybc> basically in the root of our branch there is a file called .gcfunctions
[05:17] <humphreybc> How do we know if our computer has a ssh key? and how to find it?
[05:17] <humphreybc> oops
[05:17] <humphreybc> http://www.youtube.com/watch?v=MeNXqfofbWk
[05:17] <humphreybc> copy pasta fail
[05:18] <humphreybc> so where was I? ah, right, .gcfunctions
[05:18] <humphreybc> in this file there is some basic code that sets up some buttons with a label and a command
[05:18] <humphreybc> all they run is "make show" and make clean
[05:18] <humphreybc> i just thought they were neat :)
[05:18] <humphreybc> okay, your question
[05:18] <ClassBot> vdquynh asked: How do we know if our computer has a ssh key? and how to find it?
[05:19] <humphreybc> I *think* Applications > Accessories > Passwords and Encryption Keys. "My Personal Keys" tab, and there should be a key for SSH
[05:19] <humphreybc> also, on launchpad, go to your profile (ie, mine is https://launchpad.net/~humphreybc )
[05:19] <humphreybc> and it should say you have an SSH key
[05:20] <humphreybc> see how it says "SSH keys: benjamin@benjamin-laptop" ?
[05:21] <humphreybc> https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair
[05:21] <humphreybc> vdquynh: have a look at that
[05:21] <humphreybc> it runs you through setting up an SSH key
[05:22] <humphreybc> sweet :)
[05:22] <humphreybc> so any other questions about ground control or bzr?
[05:22] <humphreybc> There is a session later on on launchpad where i explain more about launchpad features
[05:22] <humphreybc> the logs for all of these sessions can be found on http://irclogs.ubuntu.com
[05:23] <humphreybc> and the slides are on godbyk's website, also in our bzr branch under the folder "48hours"
[05:23] <humphreybc> tomorrow that folder will be renamed to "help"
[05:23] <humphreybc> to get the branch, follow the ground control video, or run "bzr branch lp:ubuntu-manual" in a terminal
[05:24] <humphreybc> any other questions?
[05:24]  * humphreybc likes it how he has a 2 hour break to get some dinner before talking about social media
[05:25] <humphreybc>  neat! well stick around because josh and Ilya have some really cool presentations coming up
[05:26] <humphreybc> (If you're using Lernid, you can check out the schedule by clicking on "Schedule" up the top) - it also gives you the times in your local timezone!
[05:27] <humphreybc> okay fellas, i'm off to grab something to eat :)
[05:27] <humphreybc> any questions you have, just ask in #ubuntu-manual on irc.freenode.net
[05:27] <humphreybc> Josh will start his session on translations in about 30 minutes
[05:52] <humphreybc> have fun dutchie!
[06:00] <dutchie> OK, here we go again ;)
[06:00] <dutchie> Hi everyone, and welcome to my talk on the translations system used by the Ubuntu Manual project.
[06:00] <dutchie> My name is Josh Holland, and I go by the nick dutchie.
[06:00] <dutchie> I've been involved in the Ubuntu Manual project since pretty much the beginning.
[06:00] <dutchie> I run a fair bit of the backend stuff, including the IRC bot, the planet, and, of course, the translations.
[06:01] <dutchie> What I'm going to cover today includes:
[06:01] <dutchie> * How to contribute a translation
[06:01] <dutchie> * A brief overview of the translation infrastructure
[06:01] <dutchie> * How to build a translated version of the manual
[06:01] <dutchie> If you've got a question, stick it in #ubuntu-classroom-chat with QUESTION: at the front and I'll answer it when appropriate.
[06:01] <dutchie> I'll also pause for questions at the end of each section.
[06:01] <dutchie> So, let's get started!
[06:01] <dutchie> (It's 6 AM here, so if I stop making sense, tell me ;) )
[06:02] <dutchie> [How to contribute a translation]
[06:03] <dutchie> (ooh, sorry - no slides for me. Ones on translation won't really be that interesting, and you've got the links to look at)
[06:03] <dutchie> This is easy! Just go to http://translations.launchpad.net/ubuntu-manual and click on the language you want to translate.
[06:03] <dutchie> You will then see the Launchpad translations UI.
[06:03] <dutchie> All you have to do now is enter your translations into the boxes
[06:04] <dutchie> They will then be reviewed, and hopefully included in the final translation!
[06:04] <dutchie> Any questions so far?
[06:06] <dutchie> [The translation infrastructure]
[06:06] <dutchie> The Ubuntu Manual and Launchpad use the GNU Gettext system of translations
[06:06] <dutchie> This is centred around two types of file: .pot files and .po files.
[06:06] <dutchie> .pot files are translation template files, and contain all of the strings that need translation
[06:07] <dutchie> Ours is called ubuntu-manual.pot, and, along with all the .po files, lives in the po/ directory at the top of the source tree
[06:07] <dutchie> You can see all of the translation files here: http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/main/files/head:/po/
[06:07] <dutchie> The .po files are the ones which actually contain the translations
[06:07] <dutchie> They are named after the language they translate, such as fr.po for the French translation, and en_GB.po for the British English one
[06:08] <dutchie> More information about the format of .pot, .po and .mo (which we don't need) files is available from http://www.gnu.org/software/gettext/gettext.html
[06:08] <dutchie> Essentially, a .po file contains a list of untranslated strings and translated strings next to each other, in a well-defined parsable format
[06:09] <dutchie> The text is indexed by file and line number to make it easy to match up where it came from
[06:09] <dutchie> GNU Gettext is mainly intended to translate software programs, rather than documentation
[06:09] <dutchie> We therefore can't use it directly, becuase it is normally used as a software library
[06:10] <dutchie> So, to translate a Python program for example, you'd do "import gettext", then pass every string that needs translating to a special function
[06:10] <dutchie> Other languages supported by gettext (all major ones) work in much the same way
[06:10] <dutchie> Instead, we use po4a, or po for anything (http://po4a.alioth.debian.org)
[06:10] <dutchie> This is a set of Perl scripts that allow you to use the infrastructure built up around translating Gettext files for your project
[06:11] <dutchie> There is a lot of infrastructure based on .po and .pot files
[06:12] <dutchie> Rosetta (Launchpad's translation interface) is an excellent example, but there are other po editors, such as po mode in Emacs, and GUI ones like poedit
[06:12] <dutchie> It supports manpages, Perl pod format, xml, sgml, TeX, plain text, ini and KernelHelp files
[06:12] <dutchie> It can be run using individual commands analogous to msgmerge, xgettext and friends, but it is easier to use the po4a(1) command and a configuration file
[06:13] <dutchie> We only need the TeX support, but as you can see, it can be used in a wide range of situations
[06:13] <dutchie> Any questions on Gettext or po4a?
[06:15] <dutchie> hmm
[06:15] <dutchie> ClassBot: wake up
[06:15] <dutchie>  < vdquynh> Question: I either translate directly in LP or I download the vi.po file to work with poedit. IS that OK or should I use po4a when offline?
[06:16] <dutchie> You, as a translator, will never need to worry about po4a
[06:16] <dutchie> That's a tool I use to generate and keep the po files up to date
[06:16] <dutchie> We'd prefer it if you worked directly on Lauchpad
[06:17] <dutchie> You'll see why in a moment when I go through updating the translations
[06:17] <dutchie> But, if you like, you can use poedit on the files in the bzr tree and commit and push like that
[06:17] <dutchie> No more questions?
[06:18] <dutchie> [How the translations are updated]
[06:18] <dutchie> I try to update the translations around every day.
[06:18] <dutchie> However, I have a busy life and I don't always manage this, so be gentle if I forget ;)
[06:18] <dutchie> There are two stages to updating the translations.
[06:18] <dutchie> 1. Updating the translated files
[06:19] <dutchie> (Pulling in the new translations from Launchpad)
[06:19] <dutchie> 2. Updating the translation .pot file
[06:19] <dutchie> (Changing the .pot file, and possibly the .po files, if any of the content has changed)
[06:19] <dutchie> The translations done on Launchpad are exported into the lp:~jshholland/ubuntu-manual/manual-trans branch
[06:20] <dutchie> (This is very clever and useful, a very handy Launchpad feature)
[06:20] <dutchie> I merge this in, which inevitably results in conflicts. These are resolved by just using the copy from LP, and discarding any local changes.
[06:20] <dutchie> This is the bit that gives Launchpad translations the "upper hand"
[06:21] <dutchie> If someone translates the same bit on Launchpad as someone else in the bzr branch, the Launchpad version will be used
[06:21] <dutchie> However, if it's unchanged, it will be picked up when Launchpad scans the branch (another awesomely cool feature)
[06:22] <dutchie> Once I've done this, I commit the merge and run the following command:
[06:22] <dutchie> $ po4a --no-translations --copyright-holder="The Ubuntu Manual Team" --package-name=ubuntu-manual --package-version=$(bzr version-info --custom --template={revno}) po4a.conf
[06:22] <dutchie> (it's a big one :) )
[06:22] <dutchie> This command updates the .pot file and .po files, without generating translated content, and sets appropriate values in the files.
[06:23] <dutchie> As I said, I'm the only one who needs to worry about po4a
[06:23] <dutchie> But, if you're interested, the po4a.conf control file is visible here: http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/main/annotate/head:/po4a.conf
[06:24] <dutchie> It's very small
[06:24] <dutchie> po4a works a lot of the details out for itself, which is quite handy
[06:24] <dutchie> This is then committed and the whole lot is pushed up to Launchpad.
[06:24] <dutchie> Launchpad then scans the branch, and imports the .po and .pot files to use as a basis for the translations done.
[06:25] <dutchie> This means that any new translations done in the branch are imported back into Launchpad
[06:25] <dutchie> (if they haven't been overwritten)
[06:25] <dutchie> The cycle then repeats.
[06:25] <dutchie> Any questions about how this all works?
[06:26] <ClassBot> vdquynh asked: how much time between the start and end of process for any language?
[06:26] <dutchie> Hard to say really
[06:27] <dutchie> All of the languages have been open the same time
[06:27] <dutchie> I'm sure that they've all got a different number of translators working on them
[06:27] <dutchie> As of now, the translation into British English (yes, that has to be done) is complete
[06:28] <dutchie> The rest are all at varying stages of completion, as you can see by going to http://translations.launchpad.net/ubuntu-manual and clicking "Show all languages"
[06:29] <dutchie> That leads fairly nicely on to freezes
[06:29] <dutchie> At the beginning, we had lots of content being written and edited
[06:30] <dutchie> People would translate something, then a day or two later, the original would change, and it'd have to be translated again
[06:30] <dutchie> This was quite a problem up to the alpha
[06:31] <dutchie> Now, though, less of the content is being changed, but this problem hasn't gone away completely
[06:31] <dutchie> So, at the beta, we intend to freeze all writing and editing
[06:31] <dutchie> This would give the translators a chance to catch up with all of the content before final release
[06:32] <dutchie> Questions on the freeze?
[06:32] <ClassBot> vdquynh asked: When an original string has been translated and changes, is the translated string automatically dismissed or flagged in some way that the translator knows that he /she has to do it again?
[06:33] <dutchie> po4a detects that the string has changed and updates the .pot and .po files
[06:33] <dutchie> This means that the string has to be translated again
[06:34] <dutchie> po4a keeps track of that sort of thing internally
[06:34] <dutchie> Just to make this clear, you can do translations now, but there is a small chance they will be lost if the original string changes
[06:35] <dutchie> Keep working from now until your language is done, then learn another language and do that one ;)
[06:35] <dutchie> [How to build a translated version of the manual]
[06:36] <dutchie> This bit was written when you didn't require Tex Live 2009 anyway
[06:36] <dutchie> so ignore it for now :)
[06:36] <dutchie> Thanks to some cool work from godbyk, our LaTeX guru, it's not too hard to see your translations in the manual.
[06:36] <dutchie> Unfortunately, we've had to use the polyglossia LaTeX package to handle the translations.
[06:36] <dutchie> This is only available with texlive 2009, which is only in the repos for Lucid (10.04).
[06:36] <dutchie> So, if you're running Karmic (9.10), you have two choices:
[06:36] <dutchie> 1. Upgrade to Lucid
[06:36] <dutchie> 2. Download and install texlive 2009 directly from upstream
[06:36] <dutchie> This set of instructions was taken from https://lists.launchpad.net/ubuntu-manual/msg00548.html (thanks godbyk)
[06:36] <dutchie> The first part of this will only apply to people running Karmic (or earlier).
[06:36] <dutchie> Step one is removing any texlive packages you've already got.
[06:36] <dutchie> You can do this on the command line via "sudo apt-get remove texlive-*" or through Synaptic.
[06:37] <dutchie> The next step is to download http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz, the install script for texlive
[06:37] <dutchie> You can then unpack the tarball by "tar -xvvzf install-tl-unx.tar.gz" and change into the newly unpacked directory
[06:37] <dutchie> Once in there, run "sudo ./install-tl". The defaults it selects are normally quite good, but you can remove the documentation packages for a smaller download (the full one is about 2.5G!)
[06:37] <dutchie> This will take quite a while, so be patient.
[06:37] <dutchie> Once this is done, change into the ubuntu-manual directory, and run pkgs/install-pkgs.sh script
[06:37] <dutchie> That's the Karmic-specific stuff out of the way. Lucid folks can just install texlive-base.
[06:37] <dutchie> It should hopefully find everything; if it doesn't, and you're on Lucid, it's safe to install the suggested ones
[06:37] <dutchie> If you're on Karmic, however, something has gone wrong with the installation.
[06:37] <dutchie> Drop into #ubuntu-manual and we'll try and help you out.
[06:37] <dutchie> So now you've got all the texlive 2009 packages installed, you can build the manual.
[06:37] <dutchie> OK, you can start listening again
[06:37] <dutchie> This is really easy once you've got everything installed
[06:37] <dutchie> This is easy: just type "make ubuntu-manual-LANG.pdf", where LANG is the language code (corresponding to one of the .po files in po/) you'd like to build.
[06:38] <dutchie> (so, to build the French version, "make ubuntu-manual-fr.pdf")
[06:38] <dutchie> All being well, the manual will now build, and you can see the fruits of your labour
[06:38] <dutchie> You may need to install some font packages. The ones you need will be in the error message from LaTeX, and can be found in a package starting with ttf-
[06:38] <dutchie> If you're having problems, ask godbyk. He should know what you need to do
[06:38] <dutchie> Any questions on that?
[06:40] <dutchie> That's pretty much all I have to say about translations.
[06:40] <dutchie> I hope this has helped you to understand how the translations, and maybe do some translations for yourself!
[06:40] <dutchie> Thanks a lot for coming along.
[06:40] <dutchie> I've now got 20 minutes to answer any questions you've got left
[06:50] <dutchie> I was obviously very comprehensive :)
[06:58] <dutchie> OK, thanks everyone for coming
[06:58] <dutchie> Next is IlyaHaykinson_ with a talk on Writing Style
[07:01] <IlyaHaykinson> hm, we need to give voice to ClassBot
[07:02] <IlyaHaykinson> ok, folks, we'll start in 2 mins
[07:02] <IlyaHaykinson> [SLIDE 1]
[07:03] <IlyaHaykinson> You can also see the slides at http://www.slideshare.net/ilyah/writing-the-ubuntu-manual
[07:06] <IlyaHaykinson> Alright. Welcome, folks.
[07:06] <IlyaHaykinson> Agenda: [SLIDE 2]
[07:06] <IlyaHaykinson> In this talk, we'll chat about how difficult it is actually to write a good manual
[07:07] <IlyaHaykinson> We'll consider what kind of an audience we're writing for, and what that means to us when writing it.
[07:07] <IlyaHaykinson> We'll discuss what our combined voice should be -- how should we relate to the reader?
[07:07] <IlyaHaykinson> And we'll briefly chat about some desktop conventions that you should use when writing.
[07:07] <IlyaHaykinson> Please feel free to ask questions, but I'll try to take them all at once in the breaks between sections.
[07:08] <IlyaHaykinson> Writing a Manual: Challenges -- [SLIDE 3]
[07:08] <IlyaHaykinson> There's a lot to be decided when writing a manual for an open project of the size of Ubuntu
[07:08] <IlyaHaykinson> we need to figure out what we include -- and, more importantly, what we leave out.
[07:08] <IlyaHaykinson> we've got to decide on grammar -- British? United States? International? what about non-English?
[07:09] <IlyaHaykinson> we need to decide on the voice -- should we be humorous? serious? playful?
[07:09] <IlyaHaykinson> we need to understand the audience that we hope will read the manual, and use that information to decide how to present the information.
[07:09] <IlyaHaykinson> finally, some pratical limitations come up -- we cannot include 1000 screenshots (the file size will be too large, it will take too long to take screenshots, etc)
[07:10] <IlyaHaykinson> so, we compromise on all of these points.
[07:10] <IlyaHaykinson> for Content, we decided to cover only the core of the Ubuntu Desktop.
[07:10] <IlyaHaykinson> for Style, we picked a relatively serious tone, and a grammar that is similar to the Ubuntu Docs team
[07:10] <IlyaHaykinson> for our Audience, we decided to go after new computer users and people new to Ubuntu -- this meant that we did not dive very deep, but provided enough information to let people accomplish some key tasks in the simplest way.
[07:10] <IlyaHaykinson> and, again, practical limitations guide us throughout.
[07:11] <IlyaHaykinson> Writing Challenges: Other Sources -- [SLIDE 4]
[07:11] <IlyaHaykinson> When writing a manual, we need to understand that almost everything that we write about has already been covered by documentation.
[07:11] <IlyaHaykinson> Some of it is Ubuntu's own, some of it comes from the community.
[07:11] <IlyaHaykinson> To the degree that we can, we need to both read and then if possible _copy_ the documentation.
[07:11] <IlyaHaykinson> This copying is limited by fit -- some of the documentation will not work for us when copied.
[07:12] <IlyaHaykinson> For example, Ubuntu's documentation is mainly oriented at specific tasks -- it rarely provides a high level overview to help a user get started and get the larger picture
[07:12] <IlyaHaykinson> instead it dives directly into specific pages and screens to help answer one particular question.
[07:12] <IlyaHaykinson> We can certainly use it to understand how something works, and can copy parts of it, but we cannot copy it in entirety -- it would not match our style or voice
[07:12] <IlyaHaykinson> The GNOME project also has a lot of documentation. Their docs are actually well-created -- well written, organized in a logical way, etc.
[07:13] <IlyaHaykinson> However, GNOME licenses using the GNU Free Documentation License, which is not compatible with the Creative Commons - Attribution - ShareAlike license that we are using.
[07:13] <IlyaHaykinson> Thus, we can read the GNOME docs, but not use them directly in the manual.
[07:13] <IlyaHaykinson> Finally, there's community documentation. Such great things like the ubuntuguide.org or any other fan pages
[07:13] <IlyaHaykinson> or user guides
[07:13] <IlyaHaykinson> Most of these are great, but most of these are also not perfect since they target experts, and not beginners
[07:14] <IlyaHaykinson> We can read them and use them in our troubleshooting sections, but not really much else.
[07:14] <IlyaHaykinson> Any questions before I move on?
[07:14] <IlyaHaykinson> ok, moving on to Our Audience
[07:14] <IlyaHaykinson> Next slide - Our Audience: New Users -- [SLIDE 5]
[07:15] <IlyaHaykinson> We've decided to focus our writing on people who are new to Ubuntu
[07:15] <IlyaHaykinson> this may also mean that they're new to computers in general
[07:15] <IlyaHaykinson> either actually new users, or just very much beginners in their skill set
[07:15] <IlyaHaykinson> For our writing, we assume that the reader knows how to use a GUI -- they know how to use the mouse, or the keyboard
[07:15] <IlyaHaykinson> they also know that there are windows and buttons and scrollbars, and generally know how to use them to get around.
[07:16] <IlyaHaykinson> They may not know that their monitor is a monitor -- lots of people call their monitor their "computer"
[07:16] <IlyaHaykinson> i've even seen people call the actual desktop the "brain"
[07:16] <IlyaHaykinson> they will not know what ethernet is, necessarily; we need to remind them about wifi.
[07:16] <IlyaHaykinson> they will certainly not know anything more complex than that.
[07:16] <IlyaHaykinson> Next slide - Our Audience: New Users -- [SLIDE 6]
[07:16] <IlyaHaykinson> So, we need to be very careful when writing to not include any jargon in our presentation.
[07:17] <IlyaHaykinson> We need to explain, in detail, everything that we mention.
[07:17] <IlyaHaykinson> we can say "click the ____ button", assuming that the person will see the button
[07:17] <IlyaHaykinson> and knows how to click
[07:17] <IlyaHaykinson> but, for example, we need to say "Click-and-hold your mouse button at the edge of the window, and drag your mouse to resize the window"
[07:17] <IlyaHaykinson> instead of assuming the person knows what to do.
[07:17] <IlyaHaykinson> we need to define all terms; in a section on printing, we may want to say "Your printer may connect to your computer using a USB cable. Before starting, plug your printer into an available USB slot on your computer."
[07:18] <IlyaHaykinson> because a user may not remember on their own
[07:18] <IlyaHaykinson> We need to be very precise in our language -- need to know the terms for everything in the operating system.
[07:18] <IlyaHaykinson> so that when we refer to a piece of the user interface, we are consistent with other documentation
[07:18] <IlyaHaykinson> and consistent with ourselves
[07:18] <IlyaHaykinson> I will cover some terms later, but there's a great guide for GNOME user interface terms at http://library.gnome.org/devel/gdp-style-guide/stable/gnome-glossary-desktop.html.en
[07:19] <IlyaHaykinson> Most importantly, when writing for new users, we need to start with very simple things. We can move on to more advanced topics only after we've repeated the simple things again, and again, and again.
[07:19] <IlyaHaykinson> For example, we may start with talking about "Click-and-hold ... to resize" at first.
[07:19] <IlyaHaykinson> And by the end of a section, just say "resize" since we can assume the user has learned a bit already.
[07:19] <IlyaHaykinson> Next slide - Our Audience: Eager to Learn -- [SLIDE 7]
[07:19] <IlyaHaykinson> We are writing for people who picked up a manual.
[07:20] <IlyaHaykinson> People who have either already installed, or interested in installing Ubuntu -- which is saying that they're a captured audience, in a way.
[07:20] <IlyaHaykinson> They are somewhat task oriented in their day to day computing life -- they have no interest in learning the underlying ways things work in Linux or Ubuntu
[07:20] <IlyaHaykinson> any more than they want to know how the Win32 API works, or that MacOS is based on Darwin.
[07:20] <IlyaHaykinson> but they _do_ care to know how to make their printer print. or their scanner scan. or their presentation saved as PDF.
[07:21] <IlyaHaykinson> because those are actually their goals.
[07:21] <IlyaHaykinson> Since we are writing a manual, they may read the manual in fairly large chunks -- many pages at once -- instead of just as a reference guide where they use the index, jump to a page, read a tiny bit, and close it.
[07:21] <IlyaHaykinson> Next slide - Our Audience: Eager to Learn -- [SLIDE 8]
[07:21] <IlyaHaykinson> So, the recommendations are aligned with this eagerness to learn
[07:21] <IlyaHaykinson> we need to keep a narrative that turns a novice into a knowledgeable user over time.
[07:22] <IlyaHaykinson> As i mentioned, start simple -- progress to complex
[07:22] <IlyaHaykinson> We need to think in terms of these user tasks -- title each section with a particular task, and cover only that one task.
[07:22] <IlyaHaykinson> Don't just write how to do something -- make sure you have some indication _why_ someone would want to do something
[07:22] <IlyaHaykinson> Use asides, callouts, and notes in the margins to keep the advanced users happy, too (godbyk's talk on LaTeX will explain how to do this, technically, in the manual)
[07:23] <IlyaHaykinson> so if there's something that you think they _might_ want to know, after reading your manual, stick it in a margin note.
[07:23] <IlyaHaykinson> and if it's advanced, and they probably do not _need_ to know it, mark it as advanced.
[07:23] <IlyaHaykinson> Finally, do not patronize -- do not be condescending to the user.
[07:23] <IlyaHaykinson> The user wants to get some work done.
[07:23] <IlyaHaykinson> they do not need to be told something is "simple"
[07:24] <IlyaHaykinson> it may not be simple for them, and  they'll assume you (the writer) is better than them
[07:24] <IlyaHaykinson> and is taunting them with your betterness
[07:24] <IlyaHaykinson> don't tell them to "just click on" something -- they may take a minute to find that something, and again will feel like you're saying their dumb if it took them a while to find it.
[07:24] <IlyaHaykinson> in general, assume that you're giving a list of instructions on how to reach a particular physical address.
[07:25] <IlyaHaykinson> you tell people "off the highway, third light, make a right; past the gas station, make a left. then, it's the second building on your right"
[07:25] <IlyaHaykinson> that same fairly serious tone should be kept when talking to the user.
[07:25] <IlyaHaykinson> Next slide: Our Audience: International -- [SLIDE 9]
[07:25] <IlyaHaykinson> We are writing in English. But we've got a lot of translations (40+). Plus, even for people reading in English, some may not have it their native language
[07:25] <IlyaHaykinson> Plus, not all humor or witty comments are universal.
[07:26] <IlyaHaykinson> Next slide: Our Audience: International -- [SLIDE 10]
[07:26] <IlyaHaykinson> So, we need to use _very_ simple language.
[07:26] <IlyaHaykinson> Always use a simpler synonym for a word.
[07:26] <IlyaHaykinson> Not "transform" but 'change'. Not "alphabetize" but "put in alphabetical order"
[07:26] <IlyaHaykinson> Use simple phrases as much as possible. Shorter sentences are better.
[07:27] <IlyaHaykinson> If you have lots of words in dependent clauses etc, it will make it hard to translate and understand.
[07:27] <IlyaHaykinson> So use a period instead of a semicolon. List out steps in an enumerated list (1. click here. 2. click there. 3. enter some text. etc)
[07:28] <IlyaHaykinson> Assume that you are speaking to an advanced English learner, basically.
[07:28] <IlyaHaykinson> As a design decision, we're using American spelling and grammar for the manual. This is consistent with the Ubuntu documentation team and other Ubuntu/Canonical guidelines.
[07:28] <IlyaHaykinson> Also, use short paragraphs. If a paragraph has more than 5 sentences, it's probably too long.
[07:29] <IlyaHaykinson> Repeat yourself. So "You may want to use a calculator to help with a calculation. To use a calculator in Ubuntu, click ..."
[07:29] <IlyaHaykinson> Saying this in two phrases helps solidify the concept, and prevents ambiguity.
[07:29] <IlyaHaykinson> Any questions before moving on to Our Voice?
[07:29] <IlyaHaykinson> Next slide: Our Voice: Confident -- [SLIDE 11]
[07:30] <IlyaHaykinson> We are writing a manual, and we are the experts. Our readers are expecting us to be condident in our opinions.
[07:30] <IlyaHaykinson> so, when writing, use language that says that you are condident in what you are saying.
[07:30] <IlyaHaykinson> When giving opinions, state them as facts.
[07:30] <IlyaHaykinson> "With Ubuntu, you can print, scan and email documents"
[07:31] <IlyaHaykinson> no need to say "With Ubuntu, you might be able to ... if you have an internet connection and your drivers work"
[07:32] <IlyaHaykinson> However, I suggest that you consider Ubuntu to not be perfect.
[07:32] <IlyaHaykinson> when talking about windows opening, when giving instructions, I generally prefer saying "Ubuntu should open..." instead of "Ubuntu will open..."
[07:32] <IlyaHaykinson> This way, if something doesn't work quite correctly, we are not lying.
[07:32] <IlyaHaykinson> My personal guideline is that if something is certain to work, use "will". If there's a chance for failure (user clicks in the wrong place, or has a different configuration) use "should"
[07:33] <IlyaHaykinson> Next slide: Our Voice: Direct and Calm -- [SLIDE 12]
[07:33] <IlyaHaykinson> Write as if you're conversing with a reader, face to face. "You may want to use a calculator. To open the calculator, click..."
[07:33] <IlyaHaykinson> or "If your email administrator advised you to use IMAP..."
[07:33] <IlyaHaykinson> As part of being calm, avoid generating excitement for Ubuntu.
[07:34] <IlyaHaykinson> we are writing a manual, not a marketing slick -- no need to use words like "best", "easiest", "simplest", "amazing" etc
[07:34] <IlyaHaykinson> instead of "In ubuntu, it's easy to do X...." say "In Ubuntu, you can do X by...."
[07:34] <IlyaHaykinson> Next slide: Our Voice: Slightly Opinionated -- [SLIDE 13]
[07:34] <IlyaHaykinson> all that said, we are _SLIGHTLY_ opinionated. Slightly <------ this is an important word
[07:34] <IlyaHaykinson> in the Linux world, there is always more than one way to do things. however, not in our manual.
[07:35] <IlyaHaykinson> in our manual, there are only a few ways.
[07:35] <IlyaHaykinson> First, we should recommend the _official_ graphical way to do something.
[07:35] <IlyaHaykinson> Second, we may recommend any simple variation or common shortcut to doing this.
[07:35] <IlyaHaykinson> But we stop there. We don't tell people the twenty ways to install software -- just the Software Center and Synaptic.
[07:35] <IlyaHaykinson> This is because we have a bias towards using the GUI, and being simple.
[07:36] <IlyaHaykinson> We also try to steer people away from bad decisions, lightly. So "You may want to pick a long password if you are worried about security."
[07:36] <IlyaHaykinson> but can also allow them the choice to make worse decisions, if there's a good reason. "If you are the only one who will be using your computer, you can decide to automatically log in without entering your password"
[07:36] <IlyaHaykinson> Next slide: Our Voice: Aligned with Users -- [SLIDE 14]
[07:37] <IlyaHaykinson> When writing sections, consider how users will want to use what you are describing.
[07:37] <IlyaHaykinson> then, name the section with a gerund form of a verb.
[07:37] <IlyaHaykinson> "Using the calculator" or "Reading your email", or "Scanning images"
[07:37] <IlyaHaykinson> setting a topic like that also helps make sure you limit the section to just one idea.
[07:37] <IlyaHaykinson> In each section, mention _why_ a user may want to do that.
[07:37] <IlyaHaykinson> for example
[07:37] <IlyaHaykinson> "If you have a photograph that you want to send over email or post online, you may want to scan it into your computer. To scan images, you will need..."
[07:38] <IlyaHaykinson> a quick intro to a section can provide the _why_ a user may want to do something that is vital to establishing context fo rthe user.
[07:38] <IlyaHaykinson> if you just say "to scan images, you will need..." -- you are not letting a user know what possible reason they will ever have that they should read the following paragraph.
[07:38] <IlyaHaykinson> <- Any questions before I move on to Conventions?
[07:39] <IlyaHaykinson> Next slide: Conventions: Attribution -- [SLIDE 15]
[07:39] <IlyaHaykinson> We have a few conventions for the manual. The main one is to write it about Ubuntu, and not about Linux.
[07:39] <IlyaHaykinson> yes, we mention in an early chapter that Ubuntu is based on Linux.
[07:39] <IlyaHaykinson> but the rest of actions should be attributed to Ubuntu.
[07:40] <IlyaHaykinson> In general, people will perceive the login process, the desktop, Nautilus, panels, window manager etc as being "Ubuntu"
[07:40] <IlyaHaykinson> utility applications should also be "Ubuntu" for purposes of this manual.
[07:40] <IlyaHaykinson> bigger application packages (Ephiphany, Totem, Open Office) should be considered big enough to warrant their own attribution.
[07:40] <IlyaHaykinson> er, Empathy :)
[07:40] <IlyaHaykinson> so for example, "The Ubuntu calculator lets you...", but "Open Office lets you..."
[07:41] <IlyaHaykinson> Also, always ensure active voice.
[07:41] <IlyaHaykinson> If you find yourself writing "It is possible to...", or "...will be opened by..." then chances are you are writing passively
[07:41] <IlyaHaykinson> when providing steps to accomplish some task, write imperatively. "Click the OK button", "Choose File, then Save to save a document"
[07:42] <IlyaHaykinson> but in general, to use an active voice, write "X will do Y" -- "Ubuntu will open a window", "You can click the OK button."
[07:42] <IlyaHaykinson> Next Slide - [SLIDE 16]
[07:42] <IlyaHaykinson> Here we'll briefly run through some common GUI terms.
[07:43] <IlyaHaykinson> button and check box -- please note that you click OK, click Cancel, click Forward, but Click _on_ other buttons (Click on Add, click on Remove Entry, etc)
[07:43] <IlyaHaykinson> check box is two words, and you either _choose_ and _option_, or _select_ / _deselect_ a check box.
[07:44] <IlyaHaykinson> I prefer "option", when possible.
[07:44] <IlyaHaykinson> Next Slide - [SLIDE 17]
[07:44] <IlyaHaykinson> nothing special here, please just review the list for proper usage
[07:44] <IlyaHaykinson> Next Slide - [SLIDE 18]
[07:45] <IlyaHaykinson> please note that double-click (and right-click and middle-click and triple-click) use a dash between the words
[07:45] <IlyaHaykinson> and you always double click _on_ something
[07:45] <IlyaHaykinson> you never drag and drop, but you drag X to Y.
[07:45] <IlyaHaykinson> Next Slide - [SLIDE 19]
[07:46] <IlyaHaykinson> A "field" is a generic term for text boxes, and other input widgets
[07:46] <IlyaHaykinson> for list boxes, I prefer to _select_ from them, but you can _choose_ as well.
[07:47] <IlyaHaykinson> note that the top menubar in Ubuntu is called Main Menu
[07:47] <IlyaHaykinson> also, that a menubar is one word. as is scrollbar, statusbar, titlebar, toolbar
[07:47] <IlyaHaykinson> you Choose from a menu
[07:47] <IlyaHaykinson> [SLIDE 20]
[07:48] <IlyaHaykinson> note the difference between login and log in -- login is a noun or adjective ("remember your login", "start the login process") but log in is the verb -- "please log in to Ubuntu"
[07:48] <IlyaHaykinson> same with log out, shut down, etc.
[07:48] <IlyaHaykinson> for radio button widgets, please use "option"
[07:48] <IlyaHaykinson> Last Slide - [SLIDE 21]
[07:49] <IlyaHaykinson> note that you click _on_ a tab
[07:49] <IlyaHaykinson> and that you _use_ a text box to _specify_ -- however _enter_ something in the /name/ field is better still
[07:49] <IlyaHaykinson> <<-- This concludes my presentation. Any questions?
[07:50] <IlyaHaykinson> Please see the terms document -- http://library.gnome.org/devel/gdp-style-guide/stable/gnome-glossary-desktop.html.en -- for more info
[07:50] <IlyaHaykinson> Or the list of user actions in GNOME -- http://library.gnome.org/devel/gdp-style-guide/stable/gnome-glossary-user-actions.html.en -- for action names
[07:50] <IlyaHaykinson> Finally, for more tips on writing for an international audience, see http://tc.eserver.org/21590.html
[07:51] <IlyaHaykinson> Alright, thank you for attending! next session in 9 minutes!
[08:01] <humphreybc> so what's the attendance like?
[08:01] <humphreybc> (join #ubuntu-classroom-chat to talk)
[08:03] <humphreybc> ill just wait a couple more minutes so i can finish mt icecream :P
[08:06] <humphreybc> wont be long :P
[08:06] <humphreybc> [SLIDE 1]
[08:06] <humphreybc> http://www.facebook.com/pages/The-Ubuntu-Manual/266794861575?ref=ts
[08:08] <humphreybc> how many people are actually here? could those that are here please say so in #ubuntu-classroom-chat
[08:09] <humphreybc> ok cool, sorry about the delay ive almost finished my ice cream :D
[08:11] <humphreybc> okay so we'll make a start
[08:11] <humphreybc> sorry about the delay, i've got my hand back now instead of holding a magnum
[08:11] <humphreybc> excuse me if i don't really know what i'm doing, i've been up since 3am this morning (it's now 9:15pm)
[08:11] <humphreybc> also i don't really have a plan for this session :)
[08:12] <humphreybc> okay so
[08:12] <humphreybc> social media in ubuntu projects
[08:12] <humphreybc> using web 2.0 to our advantage
[08:12] <humphreybc> why social media is important to us:
[08:12] <humphreybc> [SLIDE 2]
[08:13] <humphreybc> social media increases publicity about a project. this is good because it not only encourages more contributors to help, but it also makes sure more people actually download our end product - which is want we want!
[08:13] <humphreybc> media attention/blog posts inspire our team to work harder because they feel they are important
[08:14] <humphreybc> you are much more likely to feel good about something if your contributions are rewarded with publicity or commendation
[08:14] <humphreybc> and you are much more likely to like to be associated with a project that is visible and popular among the community
[08:14] <humphreybc> let me take some examples
[08:14] <humphreybc> the ubuntu manual project, and the boot team working on the new plymouth boot for Lucid
[08:15] <humphreybc> the boot team and plymouth are probably more important, more technical and more interesting than UMP
[08:15] <humphreybc> but we never hear anything about them, apart from the odd update
[08:16] <humphreybc> but then there's UMP, which is younger than the boot team and probably not as important or as interesting or as fundamental to the operation of Ubuntu
[08:16] <humphreybc> but because we have generated a huge amount of hype and publicity, we've had hundreds of contributors come forward willing to help, and we've been able to do 4x as much stuff as I ever envisioned us doing
[08:17] <humphreybc> I originally planned this manual to be 50 pages long, a few screenshots, written in open office and only available in english
[08:17] <humphreybc> now we've got this huge project, 250+ contributors, available in 40+ languages, 200 pages long, thousands of localized screenshots and we're even writing our own python program for it!
[08:17] <humphreybc> now none of this would have been possible if it wasn't for the extra contributors we get from:
[08:18] <humphreybc> blog posts
[08:18] <humphreybc> planet ubuntu posts
[08:18] <humphreybc> facebook page
[08:18] <humphreybc> twitter page
[08:18] <humphreybc> identi.ca page
[08:18] <humphreybc> Planet Ubuntu Manual - http://planet.interesting.co.nz
[08:18] <humphreybc> Running events like this
[08:18] <humphreybc> Ubuntu Forums survey
[08:19] <humphreybc> so, what i'm trying to say, is that with social media, you can create more publicity and attention, with more attention you get more people, with more people you not only get more help but you also get more ideas and feedback - which in turn creates a better overall product.
[08:19] <humphreybc> Not enough Ubuntu teams, or open source projects in general, advertise enough.
[08:19] <humphreybc> Loco teams should have facebook pages, the Boot team should have facebook pages and regular events to inspire people to help
[08:20] <humphreybc> also, our team works harder because they have an expectation to live up to now
[08:20] <humphreybc> if there wasn't hundreds of people commenting on blog posts saying "i can't wait for this manual!" "Ubuntu really needs this!" etc, then we wouldn't be as inspired to do a good job
[08:20] <humphreybc> [SLIDE 3]
[08:21] <humphreybc> I'll just show  you our facebook/twitter and identi.ca pages real quickly so you can get an idea of how we use them
[08:21] <humphreybc> also, join them! spread them to your friends!
[08:21] <humphreybc> http://www.facebook.com/pages/The-Ubuntu-Manual/266794861575?ref=ts
[08:22] <humphreybc> I like facebook the most. Why? Because it's suited to projects! It has the ability to schedule events where people can RSVP to, you can upload photos for people to look at, and you can post twitter style updates to keep everyone informed
[08:22] <humphreybc> oh yeah, that's another thing
[08:22] <humphreybc> transparency in a project is important
[08:22] <humphreybc> we're lucky in the open source world because everything is transparent anyway, but only if you do some digging
[08:22] <humphreybc> you could quite easily find out what the boot team are up to every day, and what they've done this day etc
[08:23] <humphreybc> but you'd have to do the looking yourself
[08:23] <humphreybc> why not make it easier by posting updates and keeping the community in the loop of your project?
[08:24] <humphreybc> by promoting transparency and keeping everyone informed, we not only hold interest, but we also show that the community and people "outside the team" are valued and important, which they are
[08:24] <humphreybc> we love feedback, we love criticism and I try to make that as clear as possible
[08:24] <humphreybc> okay, twitter
[08:24] <humphreybc> http://twitter.com/TheUbuntuManual
[08:25] <humphreybc> Twitter is, as most of you know, roughly the same as facebook but without the images and events and extra stuff
[08:25] <humphreybc> it's still popular though, of course. we have 119 followers!
[08:25] <humphreybc> and we have 177 in facebook!
[08:25] <humphreybc> so wait a second, let me get this straight
[08:25] <humphreybc> we're a team of people writing a book for an operating system that has a 1% market share
[08:25] <humphreybc> yet we have almost 200 fans on our facebook page?
[08:26] <humphreybc> another thing that projects need to do is run events like this
[08:26] <humphreybc> they achieve a lot of things
[08:26] <humphreybc> they give blogs content and news to write articles on, people read these articles and remember the project
[08:26] <humphreybc> they realise it isn't dead (which happens in the FLOSS world a lot)
[08:26] <humphreybc> these events also attract more contributors
[08:27] <humphreybc> and they inform people, they show that we're transparent and we value YOUR opinion
[08:27] <humphreybc> we've set all this up for you to come along and tell us what you think
[08:28] <humphreybc> jazz asked: will these lessons or classroom be posted so i can catch  up on what i've missed?
[08:28] <humphreybc> yes, they're all available on http://irclogs.ubuntu.com
[08:28] <humphreybc> I'll put up the exact logs on the 48 hours wiki page tomorrow :)
[08:28] <humphreybc> also, the slides are available in our bzr branch under "48hours" (tomorrow i'll change that folder to "help")
[08:29] <humphreybc> https://wiki.ubuntu.com/ubuntu-manual/48hours
[08:29] <humphreybc> So, how can you incorporate all this into your project, or your loco team?
[08:29] <humphreybc> easy, you just have to:
[08:29] <humphreybc> generate hype by creating facebook/twitter accounts
[08:30] <humphreybc> email blog sites and tell them about your project or team
[08:30] <humphreybc> email ubuntu members with a blog on Planet Ubuntu and ask them to give you some hangtime on the planet
[08:30] <humphreybc> run an event to explain what your project or team does
[08:31] <humphreybc> if you're a loco team, attach yourself to a bigger project and ride off the wave that they're creating
[08:31] <humphreybc> and, be unique, be ambitious, be creative
[08:31] <humphreybc> be different
[08:32] <humphreybc> oh and read jono bacons book "The Art of Community" - it's available free www.artofcommunityonline.org/
[08:32] <humphreybc> [SLIDE 4]
[08:32] <humphreybc> So, how can you help us?
[08:33] <humphreybc> you can help the project in a tonne of ways, from programming to artwork, to writing a chapter or editing one etc etc
[08:33] <humphreybc> but if you don't feel confident in those roles, we are still looking for someone to help me maintain the facebook and twitter and identi.ca accounts
[08:33] <humphreybc> the logo/screenshots need to be updated on those accounts, and we need constant tweets and updates to keep the hype reel rolling
[08:34] <humphreybc> but if you don't feel like helping the project directly, you can also do it indirectly
[08:34] <humphreybc> if you think our project is cool, tell your friends or your loco team
[08:34] <humphreybc> or, if you have some people who fit into our target audience (parents, family members, spouse etc), give them the current Ubuntu Manual PDF and ask them to read a bit. Ask them if it makes sense, if it's easy to follow
[08:34] <humphreybc> ask them how it could be better
[08:35] <humphreybc> and then email their comments to our mailing list or come into #ubuntu-manual on irc.freenode.net and tell us what they said!
[08:35] <humphreybc> sorry about the talk being a bit jumbled guys
[08:35] <humphreybc> i'm going to reorganize it and write it down properly, i'll make some better slides and then i might make a youtube video of it
[08:36] <humphreybc> but generalize it more for projects in general, not just UMP
[08:36] <humphreybc> okay, questions? :)
[08:41] <humphreybc> jazz asked: now these projects are they all volunteer, are there any paying gigs (as in career)
[08:42] <humphreybc> that's a good question.
[08:42] <humphreybc> the FOSS world runs on volunteering, but there are companies like Canonical and Novell who employ notable people from the community
[08:42] <humphreybc> there's no guarantee you'll be employed by them for working on ubuntu
[08:43] <humphreybc> it's not meant to be an incentive, but it's a possibility
[08:43] <humphreybc> I do know that if you're in IT, employers like seeing open source experience
[08:43] <humphreybc> be it volunteer or paid, all this stuff is quite acceptable as experience for your CV/resume.
[08:44] <humphreybc> yeah, it depends what you want to get out of it
[08:44] <humphreybc> I think if you're just doing it to get a job in the end, you'll never succeed.
[08:44] <humphreybc> You need to be genuinely interested in helping out the community, working towards a goal. In our case, or my case, I want to see Ubuntu's market share increase because I think it deserves to be used in the mainstream.
[08:45] <humphreybc> One of Ubuntu's biggest flaws is lack of education
[08:45] <humphreybc> the operating system itself is great, but it's ill-educated users that don't know about it or how to use it that's not helping our cause
[08:45] <humphreybc> also the fact that people have been brought up on windows/mac and they're used to that. We need to make it easier for them to switch
[08:46] <humphreybc> But in the end, the average consumer is always wanting to get more "bang for their buck"
[08:46] <humphreybc> so if you have a $400 operating system in one hand, and a $0 one in your other hand that does all the same things as the $400 one, why wouldn't you choose the free one?
[08:47] <humphreybc> the problem we have, is that people have one eye blinded, so they can't see the free operating system in one hand
[08:47] <humphreybc> we need to open that eye and explain to them why it's better
[08:47] <humphreybc> and we need to help them adjust. it's not their fault that Microsoft has a monopoly and has forced us Windows all through school and in our workplace
[08:48] <humphreybc> but that's what they are used to because this is exactly what Microsoft has done
[08:48] <humphreybc> so we need to teach them how to convert easily
[08:48] <humphreybc> and that's what we're trying to do with UMP
[09:00] <godbyk> [SLIDE 1] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/00.html
[09:01] <godbyk> Hello, everyone.
[09:01] <godbyk> This talk will cover the basics of LaTeX: what you'll need to know as an author, editor, or translator.
[09:01] <godbyk> You can get handouts of this talk here: http://kevin.godby.org/ubuntu-manual/talks/latex-handout.pdf
[09:01] <godbyk> [SLIDE 2] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/01.html
[09:02] <godbyk> In this talk, we'll cover a basic overview of how the Ubuntu Manual project uses LaTeX.
[09:02] <godbyk> [SLIDE 3] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/02.html
[09:02] <godbyk> By this point, I'll assume that everyone knows the idea behind the Ubuntu Manual Project.
[09:03] <godbyk> We're aiming to produce a manual for beginning users in a multitude of languages.
[09:03] <godbyk> One of the most important tools we use to accomplish this is LaTeX.
[09:03] <godbyk> [SLIDE 4] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/03.html
[09:03] <godbyk> LaTeX has been around for over 20 years and it employs an underlying typesetting engine (TeX) that has been around for over 30 years.
[09:04] <godbyk> LaTeX code is similar to HTML in that you can think of it as a markup language.
[09:04] <godbyk> The .tex files contain plain text -- all the word you want to appear in the PDF -- plus some markup that tells the typesetting program how to format the text and where it goes on the page.
[09:05] <godbyk> Unlike HTML, though, TeX is a full programming language.  Luckily for you, most of the programming work has already been done, so you won't have to worry about that side of things.
[09:05] <godbyk> [SLIDE 5] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/04.html
[09:05] <godbyk> All of the code is stored in .tex files.
[09:06] <godbyk> These files are just text files and can be read and edited using your favorite text editor.
[09:06] <godbyk> There are also some more advanced editors designed just for LaTeX (including Kile and TeXMaker).  Most editors have plugins to help with LaTeX code.
[09:07] <godbyk> For most of the code you'll be using with our manual, however, a plain text editor will serve just fine.
[09:07] <godbyk> LaTeX commands begin with a backslash (\).
[09:07] <godbyk> Some LaTeX commands take no arguments (like the \dash command we'll see later},
[09:07] <godbyk> while others take 1 or more arguments.
[09:08] <godbyk> An example of a command and its argument is show on this slide: the \textbf command.
[09:08] <godbyk> The \textbf command takes a single argument: the test that is should set in bold-faced type.
[09:08] <godbyk> [SLIDE 6] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/05.html
[09:09] <godbyk> In editing this manual, we'll avoid using the low-level bold, italics, etc. commands and instead use semantic markup.
[09:09] <godbyk> Semantic markup lets us create new commands that can apply styles consistently across the entire manual.
[09:09] <godbyk> [SLIDE 7] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/06.html
[09:10] <godbyk> For instance, instead of putting each menu name in bold, we've created a \menu command.
[09:10] <godbyk> If we were to decide later that we wanted menu names to appear in italics instead, we just have to edit one line of code in the style sheet instead of searching the entire manual for any menu names.
[09:11] <godbyk> [SLIDE 8] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/07.html
[09:11] <godbyk> While you can generally get away with simple typing whatever you like into the .tex file and having LaTeX make a nice-looking PDF from it, there are a few special characters you should be aware of.
[09:12] <godbyk> The most common "special character" is the quotation mark.
[09:12] <godbyk> LaTeX knows about quotation marks -- it uses what are sometimes called "smart quotes" or "curly quotes".
[09:12] <godbyk> That is, the opening and closing quotation marks do not appear the same in the final document.
[09:13] <godbyk> When you're editing the .tex files, opening quotation marks are entered using two "backticks" or grave accents.
[09:13] <godbyk> The closing quotation marks are entered using two apostrophes.
[09:13] <godbyk> So quoted material looks ``like this''.
[09:13] <godbyk> Another special character you'll find in the manual is the dash.
[09:14] <godbyk> We use the dash to interrupt a sentence -- Hi, mom! -- or to help place emphasis on an important point.
[09:14] <godbyk> When we started writing the manual, we manually entered the dashes using three hyphens --- like this.
[09:14] <godbyk> But I've recently written a \dash command (which that no arguments) to do this for us.
[09:14] <godbyk> Using the \dash command allows us to use the proper dashes depending on the language.
[09:15] <godbyk> In US English, we use an em dash---like this---surrounded by no spaces.
[09:15] <godbyk> However, in the UK and elsewhere, they use an en dash -- like this -- surrounded by a small space.
[09:15] <godbyk> As you're editing the manual, if you see an em dash written as ---, change it to \dash.
[09:15] <godbyk> [SLIDE 9] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/08.html
[09:16] <godbyk> There are another few characters that LaTeX considers special.  These characters are normally used in LaTeX syntax.
[09:16] <godbyk> If you want one of these characters to appear as-is in the final PDF, put a backslash (\) in front of that character.
[09:17] <godbyk> If you want a backslash character itself to appear, you will need to use the \textbackslash command.
[09:17] <godbyk> (The \\ command actually inserts a line break instead of printing a backslash as you might expect.)
[09:17] <godbyk> [SLIDE 10] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/09.html
[09:18] <godbyk> The document structure of the manual has been fairly well established by this point.
[09:18] <godbyk> However, I wanted to mention these commands briefly so you'll know what they mean when you see them.
[09:18] <godbyk> Each of these commands starts a new part/chapter/section of the document.
[09:18] <godbyk> They each take a single argument -- the name of the part/chapter/section.
[09:18] <godbyk> The name is automatically formatted appropriately and put into the PDF.
[09:19] <godbyk> These commands also add the entries to the table of contents automatically.
[09:19] <godbyk> [SLIDE 11] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/10.html
[09:19] <godbyk> LaTeX doesn't really care if you want to write a paragraph on multiple lines.  It will piece them back together into a paragraph for you.
[09:20] <godbyk> To tell LaTeX that you want to start a new paragraph, just leave a blank between paragraphs.
[09:20] <godbyk> We use short notes in the margin of the manual to tell the reader where to find more information about a topic, either online or in another part of the manual.
[09:20] <godbyk> To create these short notes, use the \marginnote command.
[09:21] <godbyk> Just tell the \marginnote command what text you'd like it to place in the margin and it'll take care of t for you.  It's magic!
[09:21] <godbyk> [SLIDE 12] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/11.html
[09:21] <godbyk> One more special character that you should take note of: the percent sign (%).
[09:21] <godbyk> The percent sign starts a comment.
[09:21] <godbyk> LaTeX will ignore the percent sign and everything on the line after it.
[09:22] <godbyk> This is useful for making notes to yourself or another editor.  TODOs or FIXMEs, for instance.
[09:22] <godbyk> If you want a percent sign to appear in the PDF, however, you'll have to precede it with a backslash character.
[09:22] <godbyk> [SLIDE 13] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/12.html
[09:23] <godbyk> When we're providing instructions for the readers, we reference a lot of GUI elements: menu, buttons, windows, checkboxes, etc.
[09:23] <godbyk> Each of these elements has its own command to help keep their appearance consistent throughout the manual.
[09:23] <godbyk> The \menu command is used to display menu names and menu items.
[09:23] <godbyk> To separate menu items, use the \then command.
[09:24] <godbyk> As you can see, writing \menu{Applications \then Accessories\then Calculator} will produce the text "Applications > Accessories > Calculator".
[09:24] <godbyk> The \menu command used to be named the \nav command.
[09:24] <godbyk> If you encounter the \nav command while editing the manual, please update it to use the \menu command instead.
[09:25] <godbyk> Similarly, there was a \menuitem command.  This should also be updated to \menu.
[09:25] <ClassBot> vdquynh asked: Is the blank space before "\then" optional or not?
[09:25] <godbyk> vdquynh: The space is optional, yes.
[09:25] <godbyk> The \then command will try to remove any extra space around it before printing the arrow.
[09:26] <godbyk> Are there any other questions about the \menu or \then commands?
[09:26] <godbyk> [SLIDE 14] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/13.html
[09:26] <godbyk> Here is a list of the other GUI element commands we have.
[09:27] <godbyk> One other outdated command is the \option command. This should be changed to the \checkbox command if you see it.
[09:27] <godbyk> Are there any questions about any of these commands, what they refer to, or when they should be used?
[09:27] <godbyk> [SLIDE 15] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/14.html
[09:28] <godbyk> In the second part of the manual -- the advanced part -- we introduce a few useful terminal commands.
[09:28] <godbyk> To display the command prompt, user input, and terminal output, we have a special environment that wraps around these commands.
[09:29] <godbyk> The terminal environment is started with the command \begin{terminal} and finished with the command \end{terminal}.
[09:29] <ClassBot> vdquynh asked: Could you put somewhere the list of commands to be replaced? like \option should be replaced by \checkbox, etc. ?
[09:29] <godbyk> vdquynh: Yes, I will compile a list soon and post it to the mailing list.
[09:29] <godbyk> Inside the terminal environment, all of the text is printed in a monospaced font.
[09:30] <godbyk> The \prompt command simply prints a user-level bash prompt ($).
[09:30] <godbyk> For printing root prompts (#), you can use the \rootprompt command.
[09:30] <godbyk> Any time the user is typing something into a terminal, you should put that text inside a \userinput command.
[09:31] <godbyk> The terminal output can by typed like normal text.
[09:31] <godbyk> Are there any questions about the terminal environment or related commands?
[09:31] <godbyk> [SLIDE 16] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/15.html
[09:32] <godbyk> There are two different types of lists that we use in the manual: numbered lists and bulleted lists.
[09:32] <godbyk> The only difference (in the code) between the two lists is their names.
[09:32] <godbyk> The bulleted list is called 'itemize', and the numbered list is called 'enumerate'.
[09:32] <godbyk> You start and end a list with the \begin and \end commands as shown.
[09:33] <godbyk> Each item in the list starts with the \item command.
[09:33] <godbyk> Are there any questions about the list environments?
[09:33] <godbyk> [SLIDE 17] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/16.html
[09:33] <ClassBot> vdquynh asked: is there a limit in the number of characters for any \item of the list?
[09:34] <godbyk> vdquynh: There is no set limit; you can ramble on for as long as you like.
[09:34] <godbyk> There are some practical considerations that may interfere if you're typing a novel as one list item, however. :-)
[09:34] <ClassBot> dvd asked: can you control the first number in the list?
[09:35] <godbyk> dvd: You can, if necessary.  Do you have a specific instance in mind where you need to do this?
[09:36] <ClassBot> dvd asked: where the list is broken with a paragraph then continued
[09:36] <godbyk> Gotcha.  It will depend on the reason for stopping in the middle of the list.  If you encounter a situation where you'd like to do this, find me on IRC in #ubuntu-manual or email the list and I can help you out.
[09:37] <godbyk> Similar to HTML, we can include hyperlinks in the PDF.
[09:37] <godbyk> We have a couple commands that help cross-reference other chapters and sections in the manual.
[09:37] <godbyk> To cross-reference a chapter, use the \chaplink command.
[09:37] <godbyk> To cross-reference a section, use the \seclink command.
[09:38] <godbyk> Each of these commands takes a single argument: the chapter/section label.
[09:38] <godbyk> To find the label for a specific chapter or section, open the .tex file containing that chapter/section.
[09:38] <godbyk> Immediately after the \chapter or \section command, you will see a \label command.
[09:38] <godbyk> The argument to the label command is the same argument you'll use with the \chaplink and \seclink commands.
[09:39] <godbyk> All of the chapters have been assigned labels already.
[09:39] <godbyk> Only a few of the sections have.
[09:39] <godbyk> If the section you want to link to doesn't already have a label, you can create one.
[09:39] <godbyk> Right after the \section{Why Linux Is Awesome} command, add a new command: \label{sec:why-linux-is-awesome}
[09:40] <godbyk> The style we use to create the labels is to prefix the label with "ch:" for chapters and "sec:" for sections.
[09:40] <godbyk> Then follow that prefix (no spaces!) with a short version of the chapter/section names.
[09:40] <godbyk> Each 'word' should be separated by a hyphen.
[09:41] <ClassBot> vdquynh asked: I'm a bit confused here : in "\chaplink{ch:installation}" where is the "\label" command ?
[09:41] <godbyk> vdquynh: The \label command appears after the \chapter command in the installation.tex file.
[09:41] <godbyk> So the \label command is telling LaTeX, "Hey, call this chapter ch:installation."
[09:42] <godbyk> Then the \chaplink command is used as \chaplink{ch:installation} to refer to the installation chapter.
[09:42] <godbyk> Are there any other questions on \label, \chaplink, \seclink, or cross-referencing?
[09:42] <godbyk> [SLIDE 18] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/17.html
[09:43] <godbyk> A few quick notes for any translators in the crowd.
[09:43] <godbyk> When you're translating the text, make sure that you do *not* translate the LaTeX commands themselves.
[09:43] <godbyk> If the word starts with a backslash (\), it should remain as-is.
[09:43] <godbyk> Most of the arguments of the commands should be translated, however.
[09:44] <godbyk> One exception to this rule is that you should *not* translate the labels -- that is, don't translate the arguments to the \chaplink, \seclink, \ref, or \label commands.
[09:44] <godbyk> [SLIDE 19] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/18.html
[09:44] <godbyk> If you're translating it to a new language, send an email to the mailing list, please.
[09:45] <godbyk> It gives me a heads up so I can be sure that your language is supported and can be compiled.
[09:45] <godbyk> Are there any other questions about LaTeX?
[09:46] <ClassBot> vdquynh asked: I think not all fonts are supportive of every foreign language in Unicode ? Example: I often see horrible fonts used for Vietnamese in the liveCD
[09:46] <godbyk> vdquynh: That's definitely true.
[09:46] <godbyk> We're hand-selected each font on a per-language basis.
[09:47] <godbyk> That way we can use the best fonts for that particular language.
[09:47] <godbyk> If you have suggestions on good fonts to use for the language you're translating to, please email them to me or hit me up in #ubuntu-manual.
[09:47] <ClassBot> dvd asked: How do you see the output of what you are doing (never used latex before)
[09:47] <godbyk> dvd: Good question!
[09:48] <godbyk> If you want to see the English version of the manual, you can just run 'make' and it will generate a PDF called main.pdf.
[09:48] <godbyk> If you want to see a translated version of the manual, run "make ubuntu-manual-LANG.pdf"
[09:48] <godbyk> where LANG is the language code for your language.
[09:48] <godbyk> (The language codes are listed in the po/ directory in our repository.)
[09:49] <godbyk> To get started with running LaTeX, check out the ubuntu-manual code from the repository, then go into the pkgs/ directory and run the install-pkgs.sh script from the terminal.
[09:50] <godbyk> This script will check to make sure you have the proper version of LaTeX installed along with all the required Ubuntu packages (mostly fonts) and LaTeX packages.
[09:51] <godbyk> Are there any other LaTeX questions?
[09:51] <ClassBot> dvd asked: what about just installing latex from the repositories?
[09:51] <godbyk> dvd: Unfortunately, the packages in the 9.10 repositories are too old what what we need.
[09:51] <godbyk> The packages in the Lucid repositories may be new enough -- I haven't tested them yet.
[09:52] <godbyk> Installation instructions for LaTeX are on the wiki here: https://wiki.ubuntu.com/ubuntu-manual/Prerequisites
[09:52] <godbyk> Are there any other questions?
[09:53] <godbyk> If you come up with questions later (or run into problems), you can find me on IRC in the #ubuntu-manual channel.
[09:53] <godbyk> You can also email the ubuntu-manual mailing list.
[09:53] <godbyk> I will try to keep the handout up-to-date and also keep the install-pkgs.sh script updated (in case we require more fonts/packages in the future).
[09:54] <godbyk> If there are no other questions, humphreybc will be with you shortly to discuss how the Ubuntu Manual Project employs Launchpad.
[09:56] <ClassBot> vdquynh asked: Can we use the Texlive 2009 step by step installation described in prerquistes for Karmic ?
[09:56] <godbyk> vdquynh: Yes, you sure can.
[10:02] <godbyk> humphreybc is going to pass out and beg off his final talk.
[10:02] <godbyk> If you missed it the first time around, you can read a transcript of the presentation here: http://irclogs.ubuntu.com/2010/02/22/%23ubuntu-classroom.html
[10:02] <godbyk> You can grab a copy of his slides here: http://kevin.godby.org/ubuntu-manual/talks/launchpad.pdf
[10:02] <godbyk> If you have any questions, you can email the Ubuntu Manual Project at ubuntu-manual@lists.launchpad.net
[10:03] <godbyk> [SLIDE 1]
[10:04] <godbyk> https://wiki.ubuntu.com/ubuntu-manual
[10:05] <godbyk> humphreybc is going to pass out and beg off his final talk.
[10:05] <godbyk> If you missed it the first time around, you can read a transcript of the presentation here: http://irclogs.ubuntu.com/2010/02/22/%23ubuntu-classroom.html
[10:05] <godbyk> You can grab a copy of his slides here: http://kevin.godby.org/ubuntu-manual/talks/launchpad.pdf
[10:05] <godbyk> If you have any questions, you can email the Ubuntu Manual Project at ubuntu-manual@lists.launchpad.net
[10:13] <godbyk> humphreybc is going to pass out and beg off his final talk.
[10:13] <godbyk> If you missed it the first time around, you can read a transcript of the presentation here: http://irclogs.ubuntu.com/2010/02/22/%23ubuntu-classroom.html
[10:13] <godbyk> You can grab a copy of his slides here: http://kevin.godby.org/ubuntu-manual/talks/launchpad.pdf
[10:13] <godbyk> If you have any questions, you can email the Ubuntu Manual Project at ubuntu-manual@lists.launchpad.net
[18:01] <mhall119|work> good afternoon everyone
[18:02] <mhall119|work> can I see a show of hands for who's listing?
[18:04] <mhall119|work> going to give people a few minutes to arrive
[18:05] <mhall119|work> in the mean time, I'll go over what this series of classes is going to be
[18:05] <mhall119|work> there will be 4 session, 1 hour each over 4 days
[18:05] <mhall119|work> the topics to be covered on each day can be found here: https://wiki.ubuntu.com/mhall119/classes/LearningDjango
[18:06] <mhall119|work> it is meant to get you to the point where you have a working, functional Django application that you can continue to work on after this course is done
[18:07] <mhall119|work> I will be taking a different approach from some other classes
[18:07] <mhall119|work> we won't be writing a dummy program
[18:07] <mhall119|work> nor will we be looking at an existing program
[18:07] <mhall119|work> rather, we will be building a useful project that has the potential for continued development after the end of this class
[18:08] <mhall119|work> and I hope that some of you will be a part of that continued development
[18:08] <mhall119|work> specifically, we will be making a web application that will schedule session here in #ubuntu-classroom, so poor cjohnston won't have to spend so much time in wiki syntax ;)
[18:09] <mhall119|work> are there any questions about the course or what we're going to cover
[18:09] <mhall119|work> ?
[18:11] <mhall119|work> Oh, I should mention, we are using the new Classbot https://wiki.ubuntu.com/Classroom/ClassBot
[18:11] <mhall119|work> so if you start you question with "question: <text>", it'll automatically feed them to me
[18:11] <ClassBot> cjohnston asked: what is the timing schedule for the course?
[18:12] <mhall119|work> I think we are scheduled for 1500 UTC to 1600 UTC today through Friday
[18:12] <mhall119|work> cjohnston: is that correct?
[18:12] <cjohnston> 1800 UTC
[18:12] <mhall119|work> any other questions?
[18:13] <mhall119|work> ok, moving on then
[18:13] <mhall119|work> What is Django?
[18:13] <mhall119|work> Django is a web application framework for Python
[18:14] <mhall119|work> it provides a lifecycle for HTTP request processing
[18:14] <mhall119|work> it also provides a very large collection of classes and libraries for making it easy to write web-based applications
[18:14] <mhall119|work> as well as some of the best object-relational mapping I've used
[18:15] <mhall119|work> combined with python, it makes it very easy to start writing an application, as well as maintaining and enhancing them
[18:16] <mhall119|work> sorry, yes, 1800-1900 UTC
[18:16] <mhall119|work> Django follows a model-view-controller style, which we will see a little of today and more in the following days
[18:17] <mhall119|work> so, where can you get Django?
[18:18] <mhall119|work> well, if you're lucky enough to be running Ubuntu, you can apt-get install python-django
[18:18] <mhall119|work> otherwise you can download it from here: http://www.djangoproject.com/download/
[18:19] <mhall119|work> again, if you're lucky enough to be running Ubuntu, that's all you need to do, it will be installed in your python path automatically
[18:19] <mhall119|work> if not, you will need to run the setup.py as instructed in the docs
[18:20] <mhall119|work> I'm going to assume you all are running Ubuntu, or at least some distro that makes it easy to get Django, so I won't go into the manual setup
[18:21] <mhall119|work> if you're curious about where django is installed run this: python -c "import django; print django.__file__"
[18:22] <mhall119|work> if you're ever curious about how Django does something, the source is right there for you to inspect
[18:22] <mhall119|work> any questions before we start creating our project?
[18:23] <mhall119|work> for time, I've created a bzr repository that will walk through everything we're going to discuss
[18:23] <mhall119|work> I'll give the commands you would use, but you don't need them this time around
[18:25] <mhall119|work> okay, so the first thing you would do for a django project is "django-admin startproject $projectname"
[18:25] <mhall119|work> for our example, I ran "django-admin startproject classroom_scheduler"
[18:26] <mhall119|work> and if you run "bzr branch -r tag:day1.3 lp:classroom-scheduler" you will get a copy of what that created
[18:27] <mhall119|work> if you "cd classroom-scheduler/classroom_scheduler" you will see the files that get created
[18:28] <mhall119|work> manage.py is what you will use to control your django project
[18:28] <mhall119|work> settings.py is where you configure your project (more on that next)
[18:29] <mhall119|work> and urls.py is what you use to connect a URL to the code you want to handle that request
[18:29] <mhall119|work> any questions so far?
[18:29] <mhall119|work> okay, moving right along then
[18:30] <mhall119|work> a project in django is composed of a collection of applications
[18:30] <mhall119|work> if you look at the bottom of settings.py, you will see the INSTALLED_APPS array
[18:30] <mhall119|work> this is what tells django what applications make up this project
[18:31] <mhall119|work> and, as you can see, there's already some helpful applications installed for you
[18:32] <mhall119|work> since a project doesn't do much without applications, our next step is to create an application for the functionality we want to add
[18:32] <mhall119|work> to do that, you would cd to the project directory and run "django-admin startapp $appname"
[18:32] <mhall119|work> for this example, I ran "django-admin startapp class"
[18:33] <mhall119|work> and if you run "bzr pull -r tag:day1.4" you will get that
[18:34] <mhall119|work> and now you should see a "class" directory under the project root
[18:34] <mhall119|work> and under there you will see tests.py, views.py and models.py
[18:35] <mhall119|work> remember I said that Django uses the model-view-controller pattern?  Well here is where that happens
[18:35] <mhall119|work> first things first though, we need to configure our project
[18:36] <mhall119|work> look at the top of settings.py in the project root, and you will see fields for configuring the database connection
[18:36] <mhall119|work> this connection will be used throughout Django
[18:36] <ClassBot> sucotronic asked: is the tests.py some kind of unit testing?
[18:37] <mhall119|work> I believe so, that's something new that I haven't done much with
[18:37] <mhall119|work> hopefully there will be classes on unit testing in Django in the future
[18:37] <mhall119|work> for this course, we're going to focus on views.py and models.py
[18:38] <mhall119|work> so, our next step is to tell our project where to find out database and application
[18:38] <mhall119|work> for testing, it's easiest to just use 'sqlite3' as the database, so you don't have to go through the trouble of setting up a server
[18:39] <mhall119|work> so run "bzr pull -r tag:day1.5" and then look at settings.py again
[18:39] <mhall119|work> or run "bzr diff -r tag:day1.4" to see the changes
[18:40] <mhall119|work> all that I did was set the engine to use sqlite3, with the file classroom_scheduler.db as the database file
[18:41] <mhall119|work> I also added 'classroom_scheduler.class' to the INSTALLED_APPS list
[18:41] <mhall119|work> now that Django knows where to look for the database, we have to initialize it
[18:42] <mhall119|work> to do this, run "python manage.py syncdb" from the project root
[18:42] <mhall119|work> this will create the sqlite.db file, necessary tables, and initial values needed
[18:42] <mhall119|work> it should prompt you for an admin user, just enter a username and password you'll remember
[18:43] <mhall119|work> you should now see the file classroom_scheduler.db in the project's root
[18:43] <mhall119|work> you can also "sqlite3 classroom_scheduler.db" if you needed to access it directly
[18:44] <mhall119|work> alright, so now we have our project, our application, and our database, it's time to make it actually do something
[18:44] <mhall119|work> any questions before we move on?
[18:45] <mhall119|work> ok, moving on
[18:46] <mhall119|work> a view in Django is nothing more than a function that takes an HttpRequest, and returns an HttpResponse
[18:46] <mhall119|work> there's a lot more you can do in between, but that's the essence of it
[18:46] <mhall119|work> so, we're going to create our first view
[18:47] <mhall119|work> run "bzr pull -r tag:day1.6"
[18:47] <mhall119|work> now, when you look at classroom_scheduler/class/views.py, you should see the function "class_home"
[18:47] <mhall119|work> and you can see that it gets 'request' as an argument
[18:48] <mhall119|work> and all I'm doing is stuffing some HTML into an HttpResponse object
[18:49] <mhall119|work> note that I had to import HttpReponse from django.http at the top of views.py
[18:49] <mhall119|work> view functions can be named anything you want, and for the most part can be placed anywhere you want, as long as python can find them
[18:50] <mhall119|work> now that we have our view, we need to give the user a path to it
[18:50] <mhall119|work> to do that, we map it to a url in urls.py in the project root
[18:51] <mhall119|work> again, run "bzr pull -r tag:day1.7" to get the updatre
[18:51] <mhall119|work> and "bzr diff -r tag:day1.6" to see what changed
[18:51] <mhall119|work> in this case, it was only one line in urls.py
[18:52] <mhall119|work> with Django, you use a regular expression to match the URL of a request, and then forward that request to the view
[18:52] <mhall119|work> '^class/' will match a url like http://host:port/class/
[18:53] <mhall119|work> django will try each pattern in the urlpatterns list, and short-circuit on the first one that matches
[18:54] <mhall119|work> so if you want to have both '^class/(.*)' and '^class/my_view/', you need to make sure the my_view one comes first
[18:55] <mhall119|work> alright, now it's time to see what we've made
[18:55] <mhall119|work> from the project root, run "python manage.py runserver"
[18:56] <mhall119|work> if there aren't any problems, it should tell you that django is running on http://127.0.0.1:8000
[18:56] <mhall119|work> and if you go to http://127.0.0.1:8000/class/ you should see the output of our view
[18:57] <mhall119|work> and it should look something like this: http://growingupfree.org:8001/class/
[18:57] <mhall119|work> and that concludes our first day of learning django
[18:57] <mhall119|work> are there any questions?
[18:58] <mhall119|work> okay, well then please come back tomorrow for part 2, where we will start making our models
[18:59] <mhall119|work> you can always email me at mhall119@ubuntu.com if you have any questions later