=== kermiac_ is now known as kermiac | ||
=== kermiac is now known as kermiac_ | ||
=== epkugelmass is now known as Guest94977 | ||
=== edson is now known as ecanto | ||
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi | ||
=== mhall119|work is now known as mhall119|SCaLE8x | ||
=== epkugelmass is now known as Guest67005 | ||
=== ShadowChild is now known as lukjad86 | ||
=== kermiac_ is now known as kermiac | ||
=== kermiac is now known as kermiac_ | ||
humphreybc | yay! | 14:58 |
---|---|---|
humphreybc | https://wiki.ubuntu.com/ubuntu-manual/ | 14:59 |
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: An introduction to the project - Instructor: humphreybc || Questions in #ubuntu-classroom-chat | ||
humphreybc | okay, hi everyone | 15:02 |
humphreybc | won't be a second we're just sorting out some last minute stuff | 15:02 |
humphreybc | So i'll just explain how we can ask questions, presuming it works xD | 15:02 |
humphreybc | If you want to ask a question, preface it with QUESTION: | 15:03 |
humphreybc | and I'll answer them either straight away or when i have time | 15:03 |
humphreybc | set /mode +v $godbyk | 15:03 |
humphreybc | nope | 15:03 |
humphreybc | hehe | 15:03 |
humphreybc | right! we're in business | 15:04 |
humphreybc | apart from the slideshow | 15:04 |
humphreybc | navigate to here guys, http://kevin.godby.org/ubuntu-manual/talks/ | 15:04 |
humphreybc | Lernid should do it automagically | 15:04 |
humphreybc | and you want to download "intro.pdf" | 15:05 |
humphreybc | Lernid doesn't seem to let you download files, so you might have to go in your browser | 15:05 |
humphreybc | sorry about this | 15:05 |
humphreybc | okay so i'm going to jump back to the main wiki page, https://wiki.ubuntu.com/ubuntu-manual | 15:06 |
humphreybc | I'm going to presume everyone has the slides now... :P | 15:06 |
ClassBot | MrLimeni asked: Should we see slideshow inside lernid? | 15:07 |
humphreybc | MrLimeni: yes, you should in theory - but at the moment it isn't working because of a technical problem :( | 15:07 |
humphreybc | We should have it working by the second set of sessions | 15:07 |
humphreybc | Sorry about that | 15:08 |
humphreybc | okay, so we'll start :) | 15:08 |
humphreybc | Hi everyone, my name is Benjamin Humphrey and I'm the leader of the UMP - Ubuntu Manual Project | 15:08 |
humphreybc | What i'll be covering today is listed in the first slide, but basically I'll explain what the project is, who it's for, what we want to achieve and how we'll achieve it | 15:09 |
humphreybc | I'll also talk about the key people, quickshot, and of course how you can help :) | 15:09 |
humphreybc | If you scroll down and have a look at slide 2 | 15:09 |
humphreybc | and also you can read some of the wiki page in Lernid above, if you're using Lernid | 15:09 |
ClassBot | andypiper asked: I assume you prefer Benjamin rather than a shorter form? :-) | 15:10 |
humphreybc | andypiper: I don't mind, you can call me Benjamin or Ben :) | 15:10 |
humphreybc | So basically I started out the manual project at the end of last year | 15:10 |
humphreybc | I was a beginner to Ubuntu once too, and I found a lack of up to date documentation in an easy to understand language | 15:11 |
humphreybc | Inspired by Keir Thomas' Pocket Guide and other types of books, I began writing the manual myself - but then realised it would be beneficial to open it on launchpad for collaboration. So I did :) | 15:11 |
humphreybc | We soon got a lot of media attention because apparently people thought our project was quite cool, and we got a lot of contributors in a short space of time. Since then, in the last 2 months, we've made a huge amount of progress and I am very very grateful to those who have helped so far | 15:12 |
humphreybc | So moving to the manual itself, we use a combination of LaTeX, bzr and launchpad to manage the key parts of the project | 15:13 |
humphreybc | LaTeX is good because it supports a tonne of output formats, is fairly easy to get into and learn, and also supports translations | 15:13 |
humphreybc | At the moment we're just focussing on a PDF for lucid | 15:13 |
humphreybc | but in the future we will output to HTML5 as well | 15:13 |
humphreybc | We are also working on different paper sizes and orientations, like double-up for printing etc | 15:14 |
humphreybc | and we are being really nice and tying paper sizes to country/language | 15:14 |
humphreybc | for example, the en_US version will be in US letter, the en_GB version will be in A4. | 15:14 |
humphreybc | We are also incorporating many localized screenshots, because a picture is worth a thousand words | 15:15 |
humphreybc | So that's an overview of the project. What we want to achieve is: | 15:15 |
humphreybc | We'd like to be on the default Ubuntu CD | 15:15 |
humphreybc | We would like to have a manual in as many languages as possible | 15:15 |
humphreybc | We would like to have a manual in as many formats as possible | 15:15 |
humphreybc | We want to make it easy and enjoyable for people of all ages to pick up Ubuntu, and that's the way it should be. We are trying to stay away from jargon and the terminal, things that make Ubuntu and Linux in general confusing | 15:16 |
ClassBot | HomoGleek asked: Space wise, what size would it be? | 15:16 |
humphreybc | HomoGleek: At the moment, we're not sure. It's a bit too hard to tell. It is about 600kb with 90 pages of text, no screenshots. We're going for 200 pages including screenshots, so probably 3-5mb. | 15:17 |
humphreybc | That's quite a lot for documentation, so we have been considering a cut down version for the CD. | 15:17 |
humphreybc | if you've looked at the manual, you'll see it's in two parts - beginner and advanced | 15:17 |
humphreybc | we could just include the beginner part on the CD | 15:18 |
humphreybc | okay so moving on | 15:18 |
humphreybc | you know what it's about, what we want to achieve | 15:18 |
humphreybc | Who it's for (slide 3) | 15:18 |
humphreybc | We are not aiming at Linux geeks - this isn't an all encompassing publication where we mention every single command on the CLI | 15:19 |
humphreybc | but on the other hand we don't say "this is a mouse." "this is a screen." | 15:19 |
humphreybc | We assume a basic understanding of what a computer is and how to use their own hardware | 15:19 |
humphreybc | And from there we teach as if they've never heard of Ubuntu | 15:19 |
humphreybc | this means that we also explain what Ubuntu is and give some history in the prologue :) | 15:20 |
humphreybc | We also take great care in explaining the community and encourage people to get involved if they're interested | 15:20 |
humphreybc | So How we're going to achieve all of this, well i've already mentioned some of the tools we're using | 15:20 |
humphreybc | Basically we try to have weekly meetings, we have an IRC channel (#ubuntu-manual), a mailing list and a wiki | 15:21 |
humphreybc | We encourage communication, ideas, feedback | 15:21 |
humphreybc | and we listen to any feedback and ideas that people have. A lot of the stuff we have done have actually just been suggestions from people who are relatively new to the project | 15:21 |
humphreybc | andypiper: yep i listened to that last night | 15:21 |
humphreybc | So basically what makes our project quite cool is that we cover a huge range of topics. We can cater for contributors who are interested in writing, or editing, or artwork, or coding, or how launchpad works | 15:22 |
humphreybc | we also have spaces for leadership, team management | 15:22 |
humphreybc | and, now that we've started quickshot, we have opportunity for programmers and UI design | 15:22 |
humphreybc | our project covers a lot of ground, and we encourage new contributors to help out as little or as much as they like | 15:23 |
humphreybc | another appealing thing about UMP is the fact that we don't have a lot of bureaucracy, we don't mess about too much, we get things done | 15:23 |
humphreybc | there is an element of planning | 15:23 |
humphreybc | but it's an exciting and fast paced environment because new stuff is happening all the time. this event was only conceived a week ago | 15:24 |
ClassBot | andypiper asked: what is quickshot? | 15:24 |
humphreybc | andypiper: Quickshot is a python application that we are developing to help us capture screenshots. I'll explain more about that in a minute. | 15:25 |
humphreybc | We also get a fair amount of media and blog attention. Just pop over to omgubuntu.co.uk or the planet and you'll see we are featured | 15:25 |
humphreybc | Also, the manual is visible - it's something you can read, see, something new and fresh. It's educating more people and it's helping Ubuntu's market share by making it easier to switch from Windows. So, it's a worthwhile cause to help, because it feels like you're doing something | 15:26 |
ClassBot | andypiper asked: what team mgmt / project mgmt roles are open? (will these be covered later) | 15:27 |
humphreybc | I'll cover these later :) | 15:27 |
ClassBot | Wutzara asked: Are there plans for a introduction manual for developers | 15:27 |
humphreybc | Good question. At the moment there aren't any plans - but it seems like a very good idea. I'll think it over, feel free to join us in #ubuntu-manual sometime to chat about it :) | 15:28 |
humphreybc | okay, so that's how we're going to reach our goal | 15:28 |
humphreybc | i'll introduce the key people really quickly | 15:28 |
humphreybc | you've met me. You can contact me at humphreybc@gmail.com | 15:28 |
humphreybc | Josh Holland (dutchie) has been working with us for quite some time. He does a lot of stuff, mainly translations, he's writing a chapter, also created our planet: http://planet.interesting.co.nz | 15:29 |
humphreybc | then there's Kevin Godbyk, godbyk, who's in the chat there >> | 15:30 |
humphreybc | he's done a great job on all the LaTeX work. You should check out the Tex code in the branch to see what goes on behind the scenese | 15:31 |
humphreybc | scenes* | 15:31 |
humphreybc | Ilya Haykinson, Jamin Day and Thorsten Wilms are author, editor and artwork respectively. Ilya helps out with a lot of stuff outside of just writing about a chapter, Jamin is coordinating the editors and Thorsten is one of the people responsible for the awesome title pages that we've got | 15:32 |
ClassBot | kyleN asked: has the team gotten approval from Ubuntu folks to include the pdfs on the install CD? | 15:32 |
humphreybc | At the moment, no. Because Lucid is an LTS and we are a new project, it would be unusual for us to get on the CD for Lucid. Also, stuff on the CD gets decided way back at the UDS, which we weren't around for. I'll be proposing the manual goes on the CD at UDS-M however, for 10.10. | 15:33 |
humphreybc | For Lucid, we will make sure the manual is very easily accessible for download, and it should be in the repos too :) | 15:33 |
humphreybc | Okay, so, Quickshot! | 15:34 |
ClassBot | kyleN asked: by "in the repos" you mean universe? | 15:34 |
humphreybc | yep | 15:34 |
humphreybc | So basically we have a 200 page manual, with about 50 places where we'd like screenshots. then it's translated into 40+ languages. If you do the math for localized screenshots, we need over 2000. In two months. | 15:35 |
humphreybc | All of these screenshots need to be on the default Lucid install, with the default theme etc | 15:35 |
humphreybc | They also need to be the same resolution, dpi, cropped properly etc | 15:35 |
humphreybc | It would be a nightmare to manually get people to take these shots and organize them somewhere so we can easily put them back into latex | 15:36 |
humphreybc | so, I thought up the idea for Quickshot. | 15:36 |
humphreybc | I'm designing the UI and ubuntujenkins and Tommy Brunn are writing the code for it | 15:36 |
humphreybc | it's written in Python, using Quickly and Glade for the UI | 15:36 |
humphreybc | Basically what it does is create a new user for you, prompt you to login to that new user | 15:37 |
humphreybc | then it starts up and pulls a bzr branch for your language. in the bzr branch we have a series of folders and empty files that denote what shots haven't been taken yet. (we might include descriptions in the empty files, not sure yet). Quickshot recognizes these as shots that need to be taken and tells the user what shot is required by choosing the first one on the list | 15:38 |
humphreybc | It asks the user to set up their computer to match the description, then takes the shot. It saves shots in the local bzr branch and when the user is done, pushes the branch and files an auto merge with launchpad | 15:38 |
humphreybc | it's a bit more complicated than that, but the idea is to fully automate pretty much everything except the user having to set up their desktop for the shot | 15:39 |
humphreybc | If you can see in the chat, Tommy just said that if you know Python, we need you! | 15:39 |
humphreybc | We're on a very tight schedule for Quickshot as well, we want it to be finished by March 18th so we can start capturing screenshots. The idea is to use the Ubuntu Global Jam to get lots of people screenshotting :) | 15:39 |
humphreybc | Most likely we won't get screenshots done for _all_ languages in time for Lucid. We are going to prioritize the languages and target about 20 to get finished for Lucid. The rest will still be released, but with english screenshots until we slowly replace them over the next 6 months leading up to 10.10 | 15:40 |
humphreybc | You can get quickshot by visiting http://launchpad.net/quickshot | 15:41 |
humphreybc | Righto, so, how you can help! | 15:42 |
humphreybc | http://wiki.ubuntu.com/ubuntu-manual#Contributions | 15:42 |
humphreybc | last slide | 15:42 |
humphreybc | so what we need really in priority would be | 15:43 |
humphreybc | Editors, Python programmers, Authors, Screenshotters, Artwork guys | 15:43 |
humphreybc | And if you feel none of that is up to you, we still have small slots available for maintaining stuff like Twitter account, Facebook etc | 15:43 |
humphreybc | Basically if you want to help, you should be able to get all the information you need from 48 hours | 15:44 |
humphreybc | I'm holding a session at 1700 that explains how you can download the branch | 15:44 |
humphreybc | Kevin is holding a session on LaTeX | 15:44 |
humphreybc | And of course there is always someone in #ubuntu-manual that can help. We have over 250 people in the team around the world, so no matter what your timezone, i'm sure there'll be someone awake and working on the project :) | 15:45 |
humphreybc | Okay, so any questions? | 15:45 |
ClassBot | kyleN asked: Can you address the potential overlap/relatinoship with ubuntu-docs? | 15:46 |
humphreybc | Sure. | 15:46 |
humphreybc | We do have an overlap in content, but when you boil it down, it really isn't a huge overlap. Not to rubbish the docs team work at all, but I myself have found a lot of the wiki docs to be outdated, and the system docs to be slow to open, hard to use and generally not that fantastic. I think the docs team are working to improve both of these for Lucid+1, based on what's been happening with UMP | 15:48 |
humphreybc | I am going to discuss collaboration with the docs team, and I have already offered the full use of our content anyway | 15:48 |
humphreybc | We are collaborating with the Ubuntu Learning Project as well, and after Lucid we're porting a large chunk of our manual into ASCII for them to use in classes like this | 15:48 |
humphreybc | I'm sure that there will be a place where the docs team and UMP can work in harmony :) | 15:49 |
ClassBot | Wutzara asked: are there special improvements about LaTeX in Ubuntu - especially Editor-Improvements we can use? | 15:49 |
humphreybc | What do you mean by "in Ubuntu?" | 15:49 |
humphreybc | We're actually using a newer version of LaTeX that's not in the repositories yet. We're using LaTeX 2009, because it makes it possible to support a number of extra characters for languages like arabic and chinese, as well as provide better tools for the glossary | 15:50 |
humphreybc | Gedit does have a LaTeX thing where it colours the commands for you | 15:50 |
humphreybc | It is very easy to use LaTeX, trust me :) | 15:51 |
humphreybc | If you're using Ground Control, you don't even have to use the terminal to compile the manual | 15:51 |
humphreybc | we actually have buttons to compile the manual and also clean the compiled files afterwards, but I'll talk about that in the ground control session | 15:51 |
humphreybc | godbyk has a great presentation lined up for LaTeX | 15:51 |
humphreybc | Yeah that's another thing we try to do with UMP - we are trying to make it as easy as possible for anyone to help out, regardless of your experience with Ubuntu | 15:53 |
humphreybc | Our wiki is quite comprehensive (it actually needs a search bar!) so i'm sure you'll be able to find help there or in #ubuntu-manual, or the mailing list :) | 15:53 |
humphreybc | Okay so I think we'll call it the end of that session | 15:54 |
humphreybc | You can grab the PDF slides for the next talk here: http://kevin.godby.org/ubuntu-manual/talks/ | 15:54 |
humphreybc | you'll want "writingstyle.pdf" for Ilya's talk on writing style | 15:55 |
humphreybc | I've looked through the slides and it looks like he's got a good session planned. Even if you aren't interested in writing for UMP, it will be useful for writing essays for uni or reports for work :D | 15:56 |
IlyaHaykinson | Hi folks. We'll wait for another few minutes to start. | 15:58 |
IlyaHaykinson | You can also view the slides at http://www.slideshare.net/ilyah/writing-the-ubuntu-manual | 16:00 |
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Writing style - Instructor: IlyaHaykinson || Questions in #ubuntu-classroom-chat | ||
IlyaHaykinson | We will start in 1 minutes | 16:04 |
IlyaHaykinson | 1 minute | 16:04 |
IlyaHaykinson | Alright. Welcome, folks. Since we're having issues with the slide integration for this talk, I'll post direct links to the slide on Slideshare (http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/1) | 16:07 |
IlyaHaykinson | http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/1 | 16:07 |
IlyaHaykinson | Agenda: http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/2 | 16:07 |
IlyaHaykinson | In this talk, we'll chat about how difficult it is actually to write a good manual | 16:08 |
IlyaHaykinson | We'll consider what kind of an audience we're writing for, and what that means to us when writing it. | 16:08 |
IlyaHaykinson | We'll discuss what our combined voice should be -- how should we relate to the reader? | 16:08 |
IlyaHaykinson | And we'll briefly chat about some desktop conventions that you should use when writing. | 16:09 |
IlyaHaykinson | Please feel free to ask questions, but I'll try to take them all at once in the breaks between sections. | 16:09 |
IlyaHaykinson | Writing a Manual: Challenges -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/3 | 16:09 |
IlyaHaykinson | There's a lot to be decided when writing a manual for an open project of the size of Ubuntu | 16:10 |
IlyaHaykinson | we need to figure out what we include -- and, more importantly, what we leave out. | 16:10 |
IlyaHaykinson | we've got to decide on grammar -- British? United States? International? what about non-English? | 16:10 |
IlyaHaykinson | we need to decide on the voice -- should we be humorous? serious? playful? | 16:11 |
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. | 16:11 |
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) | 16:12 |
IlyaHaykinson | so, we compromise on all of these points. | 16:12 |
IlyaHaykinson | for Content, we decided to cover only the core of the Ubuntu Desktop. | 16:12 |
IlyaHaykinson | for Style, we picked a relatively tone, and a grammar that is similar to the Ubuntu Docs team | 16:12 |
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. | 16:13 |
IlyaHaykinson | and, again, practical limitations guide us throughout. | 16:13 |
IlyaHaykinson | Writing Challenges: Other Sources -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/4 | 16:14 |
IlyaHaykinson | When writing a manual, we need to understand that almost everything that we write about has already been covered by documentation. | 16:14 |
IlyaHaykinson | Some of it is Ubuntu's own, some of it comes from the community. | 16:14 |
IlyaHaykinson | To the degree that we can, we need to both read and then if possible _copy_ the documentation. | 16:15 |
IlyaHaykinson | This copying is limited by fit -- some of the documentation will not work for us when copied. | 16:15 |
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 | 16:16 |
IlyaHaykinson | instead it dives directly into specific pages and screens to help answer one particular question. | 16:16 |
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 | 16:17 |
IlyaHaykinson | The GNOME project also has a lot of documentation. Their docs are actually well-created -- well written, organized in a logical way, etc. | 16:17 |
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. | 16:18 |
IlyaHaykinson | Thus, we can read the GNOME docs, but not use them directly in the manual. | 16:18 |
IlyaHaykinson | Finally, there's community documentation. Such great things like the ubuntuguide.org or any other fan pages | 16:18 |
IlyaHaykinson | or user guides | 16:18 |
IlyaHaykinson | Most of these are great, but most of these are also not perfect since they target experts, and not beginners | 16:19 |
IlyaHaykinson | We can read them and use them in our troubleshooting sections, but not really much else. | 16:19 |
IlyaHaykinson | Any questions before I move on? | 16:19 |
IlyaHaykinson | ok, moving on to Our Audience | 16:20 |
IlyaHaykinson | Next slide - Our Audience: New Users -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/5 | 16:20 |
IlyaHaykinson | We've decided to focus our writing on people who are new to Ubuntu | 16:21 |
IlyaHaykinson | this may also mean that they're new to computers in general | 16:21 |
IlyaHaykinson | either actually new users, or just very much beginners in their skill set | 16:22 |
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 | 16:22 |
IlyaHaykinson | they also know that there are windows and buttons and scrollbars, and generally know how to use them to get around. | 16:22 |
IlyaHaykinson | However, we also assume they don't really know their _names_ for things. | 16:23 |
IlyaHaykinson | They may not know that their monitor is a monitor -- lots of people call their monitor their "computer" | 16:23 |
IlyaHaykinson | i've even seen people call the actual desktop the "brain" | 16:23 |
IlyaHaykinson | they will not know what ethernet is, necessarily; we need to remind them about wifi. | 16:24 |
IlyaHaykinson | they will certainly not know anything more complex than that. | 16:24 |
IlyaHaykinson | Next slide - Our Audience: New Users -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/6 | 16:24 |
IlyaHaykinson | So, we need to be very careful when writing to not include any jargon in our presentation. | 16:24 |
IlyaHaykinson | We need to explain, in detail, everything that we mention. | 16:25 |
humphreybc | (I think the chat in Lernid has crashed or something) | 16:25 |
IlyaHaykinson | [sorry, moving on] | 16:26 |
IlyaHaykinson | so, We need to cover everything gently, making sure to make no assumptions on knowledge | 16:27 |
=== jack is now known as Guest21416 | ||
IlyaHaykinson | we can say "click the ____ button", assuming that the person will see the button | 16:27 |
IlyaHaykinson | and knows how to click | 16:27 |
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" | 16:28 |
IlyaHaykinson | instead of assuming the person knows what to do. | 16:28 |
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." | 16:29 |
IlyaHaykinson | because a user may not remember on their own | 16:29 |
IlyaHaykinson | We need to be very precise in our language -- need to know the terms for everything in the operating system. | 16:30 |
IlyaHaykinson | so that when we refer to a piece of the user interface, we are consistent with other documentation | 16:30 |
IlyaHaykinson | and consistent with ourselves | 16:30 |
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 | 16:30 |
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. | 16:31 |
IlyaHaykinson | For example, we may start with talking about "Click-and-hold ... to resize" at first. | 16:32 |
IlyaHaykinson | And by the end of a section, just say "resize" since we can assume the user has learned a bit already. | 16:32 |
IlyaHaykinson | Next slide - Our Audience: Eager to Learn -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/7 | 16:32 |
IlyaHaykinson | We are writing for people who picked up a manual. | 16:33 |
IlyaHaykinson | People who have either already installed, or interested in installing Ubuntu -- which is saying that they're a captured audience, in a way. | 16:33 |
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 | 16:34 |
IlyaHaykinson | any more than they want to know how the Win32 API works, or that MacOS is based on Darwin. | 16:34 |
IlyaHaykinson | but they _do_ care to know how to make their printer print. or their scanner scan. or their presentation saved as PDF. | 16:35 |
IlyaHaykinson | because those are actually their goals. | 16:35 |
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. | 16:35 |
IlyaHaykinson | Next slide - Our Audience: Eager to Learn -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/7 | 16:36 |
IlyaHaykinson | Er, http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/8 | 16:36 |
IlyaHaykinson | So, the recommendations are aligned with this eagerness to learn | 16:36 |
IlyaHaykinson | we need to keep a narrative that turns a novice into a knowledgeable user over time. | 16:36 |
IlyaHaykinson | As i mentioned, start simple -- progress to complex | 16:36 |
IlyaHaykinson | We need to think in terms of these user tasks -- title each section with a particular task, and cover only that one task. | 16:37 |
IlyaHaykinson | Don' | 16:37 |
IlyaHaykinson | Don't just write how to do something -- make sure you have some indication _why_ someone would want to do something | 16:37 |
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) | 16:38 |
IlyaHaykinson | so if there's something that you think they _might_ want to know, after reading your manual, stick it in a margin note. | 16:38 |
IlyaHaykinson | and if it's advanced, and they probably do not _need_ to know it, mark it as advanced. | 16:39 |
IlyaHaykinson | Finally, do not patronize -- do not be condescending to the user. | 16:39 |
IlyaHaykinson | The user wants to get some work done. | 16:39 |
IlyaHaykinson | they do not need to be told something is "simple" | 16:39 |
IlyaHaykinson | it may not be simple for them, and they'll assume you (the writer) is better than them | 16:39 |
IlyaHaykinson | and is taunting them with your betterness | 16:39 |
IlyaHaykinson | don't tell them to "just click on" something -- they may take a minute to find on something, and again will feel like you're saying their dumb if it took them a while to find it. | 16:40 |
IlyaHaykinson | in general, assume that you're giving a list of instructions on how to reach a particular physical address. | 16:41 |
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" | 16:41 |
IlyaHaykinson | that same fairly serious tone should be kept when talking to the user. | 16:41 |
IlyaHaykinson | Next slide: Our Audience: International -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/9 | 16:42 |
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 | 16:43 |
IlyaHaykinson | Plus, not all humor or witty comments are universal. | 16:43 |
IlyaHaykinson | Next slide: Our Audience: International -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/10 | 16:43 |
IlyaHaykinson | http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/10 | 16:43 |
IlyaHaykinson | [Hm, that didn't load correctly for me... it's slide 10, anyways] | 16:44 |
IlyaHaykinson | So, we need to use _very_ simple language. | 16:44 |
IlyaHaykinson | Always use a simpler synonym for a word. | 16:44 |
IlyaHaykinson | Not "transform" but 'change'. Not "alphabetize" but "put in alphabetical order" | 16:45 |
IlyaHaykinson | Use simple phrases as much as possible. Shorter sentences are better. | 16:45 |
IlyaHaykinson | If you have lots of words in dependent clauses etc, it will make it hard to translate and understand. | 16:45 |
IlyaHaykinson | Assume that you are speaking to an advanced English learner, basically. | 16:46 |
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. | 16:46 |
IlyaHaykinson | Also, use short paragraphs, and repeat yourself. | 16:47 |
IlyaHaykinson | So "You may want to use a calculator to help with a calculation. To use a calculator in Ubuntu, click ..." | 16:47 |
IlyaHaykinson | Saying this in two phrases helps solidify the concept, and prevents ambiguity. | 16:48 |
IlyaHaykinson | Next slide: Our Voice: Confident -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/11 | 16:48 |
IlyaHaykinson | We are writing a manual, and we are the experts. Our readers are expecting us to be condident in our opinions. | 16:49 |
IlyaHaykinson | so, when writing, use language that says that you are condident in what you are saying. | 16:50 |
IlyaHaykinson | When giving opinions, state them as facts. | 16:51 |
IlyaHaykinson | "With Ubuntu, you can print, scan and email documents" | 16:51 |
IlyaHaykinson | no need to say "With Ubuntu, you might be able to ... if you have an internet connection and your drivers work" | 16:52 |
IlyaHaykinson | However, I suggest that you consider Ubuntu to not be perfect. | 16:52 |
IlyaHaykinson | when talking about windows opening, when giving instructions, I prefer saying "Ubuntu should open..." instead of "Ubuntu will open..." so that if something breaks, we are not lying. | 16:53 |
IlyaHaykinson | Next slide: Our Voice: Direct and Calm -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/12 | 16:53 |
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..." | 16:54 |
IlyaHaykinson | or "If your email administrator advised you to use IMAP..." | 16:54 |
IlyaHaykinson | As part of being calm, avoid generating excitement for Ubuntu. | 16:55 |
IlyaHaykinson | we are writing a manual, not a marketing slick -- no need to use words like "best", "easiest", "simplest", "amazing" etc | 16:55 |
IlyaHaykinson | instead of "In ubuntu, it's easy to do X...." say "In Ubuntu, you can do X by...." | 16:55 |
IlyaHaykinson | Next slide: Our Voice: Slightly Opinionated -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/13 | 16:56 |
IlyaHaykinson | all that said, we are _SLIGHTLY_ opinionated. Slightly <------ this is an important word | 16:56 |
IlyaHaykinson | in the Linux world, there is always more than one way to do things. however, not in our manual. | 16:56 |
IlyaHaykinson | in our manual, there are only a few ways. | 16:56 |
IlyaHaykinson | First, we should recommend the _official_ graphical way to do something. | 16:57 |
IlyaHaykinson | Second, we may recommend any simple variation or common shortcut to doing this. | 16:57 |
IlyaHaykinson | But we stop there. We don't tell people the twenty ways to install software -- just the Software Center and Synaptic. | 16:57 |
IlyaHaykinson | This is because we have a bias towards using the GUI, and being simple. | 16:58 |
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." | 16:58 |
IlyaHaykinson | but can also allow them the choice to make worse decisions. "If you are the only one who will be using your computer, you can decide to automatically log in without entering your password" | 16:59 |
IlyaHaykinson | [note -- we will run over on this prentation by about 5-10 mins] | 16:59 |
IlyaHaykinson | Next slide: Our Voice: Aligned with Users -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/14 | 16:59 |
IlyaHaykinson | When writing sections, consider how users will want to use what you are describing. | 17:00 |
IlyaHaykinson | then, name the section with a gerund form of a verb. | 17:00 |
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Using Ground Control to make changes - Instructor: humphreybc || Questions in #ubuntu-classroom-chat | ||
humphreybc | just ignore that, we'll go into the Ground Control time slot a wee bit | 17:00 |
IlyaHaykinson | "Using the calculator" or "Reading your email", or "Scanning images" | 17:01 |
IlyaHaykinson | setting a topic like that also helps make sure you limit the section to just one idea. | 17:01 |
IlyaHaykinson | In each section, mention _why_ a user may want to do that. | 17:01 |
IlyaHaykinson | for example | 17:01 |
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..." | 17:02 |
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. | 17:02 |
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. | 17:03 |
IlyaHaykinson | next slide: Conventions: Attribution -- http://www.slideshare.net/ilyah/writing-the-ubuntu-manual/15 | 17:03 |
IlyaHaykinson | We have a few conventions for the manual. The main one is to write it about Ubuntu, and not about Linux. | 17:04 |
IlyaHaykinson | yes, we mention in an early chapter that Ubuntu is based on Linux. | 17:04 |
IlyaHaykinson | but the rest of actions should be attributed to Ubuntu. | 17:04 |
IlyaHaykinson | In general, people will perceive the login process, the desktop, Nautilus, panels, window manager etc as being "Ubuntu" | 17:05 |
IlyaHaykinson | utility applications should also be "Ubuntu" for purposes of this application. | 17:05 |
IlyaHaykinson | bigger application packages (Ephiphany, Totem, Open Office) should be considered big enough to warrant attribution. | 17:05 |
IlyaHaykinson | so for example, "The Ubuntu calculator lets you...", but "Open Office lets you..." | 17:06 |
IlyaHaykinson | Also, always ensure active voice. | 17:06 |
IlyaHaykinson | If you find yourself writing "It is possible to...", or "...will be opened by..." then chances are you are writing passively | 17:07 |
IlyaHaykinson | to use an active voice, write "X will do Y" -- "Ubuntu will open a window", "You can click the OK button." | 17:07 |
IlyaHaykinson | when describing steps, write imperatively. "Click the OK button", "Choose File, then Save to save a document" | 17:08 |
ClassBot | humphreybc_lerni asked: But we should assume that Ubuntu might not actually open a window? Going back to an earlier slide you said we shoudn't assume it "will" do something | 17:09 |
IlyaHaykinson | Good question -- it's _better_ to not make assumptions. however, i think it's fine to use both "will" as well as 'should' | 17:10 |
IlyaHaykinson | if you have any doubt about the user following instructions correctly, use "should". | 17:10 |
IlyaHaykinson | if you think something will definitely happen (i.e. clicking on the Calculator menu item will pretty much certainly open the calculator), use "Will" | 17:11 |
IlyaHaykinson | alright, this concludes my talk. there are a few more slides that cover some common GUI terms such as button, check box, dialog etc, and some notes on referring to these GUI items correctly. | 17:11 |
IlyaHaykinson | Please see the terms document -- http://library.gnome.org/devel/gdp-style-guide/stable/gnome-glossary-desktop.html.en -- for more info | 17:12 |
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 | 17:12 |
IlyaHaykinson | Finally, for more tips on writing for an international audience, see http://tc.eserver.org/.21590.html | 17:12 |
IlyaHaykinson | sorry, http://tc.eserver.org/21590.html | 17:12 |
IlyaHaykinson | Any final questions? | 17:13 |
IlyaHaykinson | Thanks all for attending! | 17:13 |
humphreybc | Okay everyone, we're going to push straight into Ground Control now. This is exciting as GC is a nice new application designed by Martin Owens and Jono Bacon | 17:14 |
humphreybc | You might have seen it on Planet Ubuntu | 17:14 |
humphreybc | take a look at this: http://launchpad.net/groundcontrol | 17:14 |
humphreybc | Ground Control is written as a python plugin for nautilus | 17:14 |
humphreybc | Basically, to install it, run the commands: | 17:15 |
humphreybc | sudo add-apt-repository ppa:doctormo/groundcontrol | 17:15 |
humphreybc | sudo apt-get install groundcontrol | 17:15 |
humphreybc | but you'll have to run sudo apt-get update | 17:15 |
humphreybc | and then killall nautilus | 17:15 |
humphreybc | I'm going to switch to the slides now | 17:15 |
humphreybc | http://www.slideshare.net/humphreybc/using-ground-control-to-make-changes | 17:15 |
humphreybc | So I really really want everyone on the UMP team to use Ground Control to push and pull | 17:16 |
humphreybc | we're the first team to use it on a wide scale project | 17:16 |
=== Navarro_ is now known as Navarro | ||
humphreybc | and it's a good opportunity for us to test it out for Martin and Jono | 17:16 |
humphreybc | Now I'm going to show you a video that I recorded yesterday that explains exactly how to install and pull our branch | 17:17 |
humphreybc | http://www.youtube.com/watch?v=MeNXqfofbWk | 17:17 |
humphreybc | with a bit of luck flash will work inside lernid | 17:17 |
humphreybc | so if you just want to watch that | 17:17 |
humphreybc | excuse my quiet voice, it was very late last night and i didn't want to wake people up :) | 17:17 |
humphreybc | let me know when everyone has finished watching the video :) | 17:21 |
humphreybc | cool, mine just finished, everyone else seen it? | 17:23 |
humphreybc | http://www.slideshare.net/humphreybc/using-ground-control-to-make-changes/2 | 17:24 |
humphreybc | righto | 17:24 |
humphreybc | so basically that's all there is to it, the video is probably the easiest way to explain stuff | 17:25 |
humphreybc | http://www.slideshare.net/humphreybc/using-ground-control-to-make-changes/3 | 17:25 |
humphreybc | tom, yes it is | 17:25 |
humphreybc | So I suppose the one thing that I definitely need to make clear is the "Download my branch" radio button | 17:25 |
humphreybc | If you choose anything else you'll either get a read only branch where you can't commit changes, or you'll get the branch but when you push it won't go straight into the branch and we'll end up with a million merge requests | 17:26 |
humphreybc | so that's not what we want :) | 17:27 |
humphreybc | http://www.slideshare.net/humphreybc/using-ground-control-to-make-changes/4 | 17:27 |
humphreybc | Okay so I'll explain how the developer buttons work | 17:27 |
humphreybc | you probably don't need to know this, other than how to use them | 17:27 |
humphreybc | but it's quite interesting | 17:27 |
humphreybc | basically ground control looks for a file in the branch called .gcfunctions | 17:27 |
humphreybc | in that file we have some very simple code that sets up one more buttons with a label and a command | 17:28 |
humphreybc | in most instances the command would be to run a script | 17:28 |
humphreybc | but because we've got such simple commands to compile the manual, like make show and make clean | 17:28 |
humphreybc | we just simply have those commands there | 17:28 |
humphreybc | As much as I want to have a button to compile into different languages, it wouldn't really work unless we had a drop down box to choose your language. | 17:29 |
humphreybc | And everyone has to have the latest version of latex with the correct fonts and things | 17:29 |
humphreybc | otherwise you'll run into errors | 17:29 |
humphreybc | Okay, so, any questions? Anyone having a problem installing and setting up Ground Control? | 17:29 |
humphreybc | Remember you'll need to be a member of the team and also have a launchpad account with an ssh key to push to the branch | 17:30 |
humphreybc | https://wiki.ubuntu.com/ubuntu-manual/Help | 17:30 |
humphreybc | if you scroll down you'll see the requirements | 17:30 |
humphreybc | launchpad account, member of the team and the project, registered an SSH key | 17:31 |
=== Navarro_ is now known as Navarro | ||
humphreybc | there are links on that page that will take you to the necessary places to sign up for launchpad etc | 17:31 |
humphreybc | i'll go back to the video for the rest of the session | 17:31 |
humphreybc | http://www.youtube.com/watch?v=MeNXqfofbWk | 17:31 |
humphreybc | (if you want to use the old fashioned command line bzr, i have actually made a video for that too - see the right of the screen under related videos) | 17:32 |
humphreybc | questions? | 17:32 |
ClassBot | d0od asked: do you have to be a member of the project in order to pull via control centrE? | 17:37 |
humphreybc | You have to member of the launchpad team page, yes. Control Centre? Do you mean Ground Control? | 17:37 |
humphreybc | Oh i'm not sure about pulling actually | 17:37 |
humphreybc | I think anyone can pull | 17:37 |
humphreybc | but you won't get the "download my branch" option unless you're a member of the team | 17:37 |
humphreybc | instead you can do the read only checkout option | 17:38 |
humphreybc | You have to be a member of The Ubuntu Manual Team on launchpad to be able to push :) | 17:38 |
ClassBot | Wutzara asked: Where is the difference between a Merge-Request and a own Branch? | 17:38 |
humphreybc | Merges are used for other projects where people can submit their changes for review | 17:38 |
humphreybc | so they would submit some changes, and if the changes were good changes, the reviewer would approve the merge into the main branch | 17:39 |
humphreybc | it's important for merge reviews to occur in system projects like the boot team, software center etc to prevent anyone from deleting all the code and then pushing straight to main | 17:39 |
humphreybc | but because we are on such a tight schedule and our branch is so busy, we don't have time to review every single revision that people make | 17:40 |
humphreybc | so we basically run the risk of someone coming along and screwing everything up, but the benefits outweigh the cons. It's easy to revert to an older revision anyway if someone does do that | 17:40 |
humphreybc | anything else? | 17:41 |
humphreybc | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/01.html | 17:53 |
godbyk | I'll wait a few more minutes before we start, since we're a bit ahead of schedule. | 17:53 |
godbyk | But if you want, you can download the PDF handout: http://kevin.godby.org/ubuntu-manual/talks/latex-handout.pdf | 17:54 |
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: LaTeX for authors and translators - Instructor: godbyk || Questions in #ubuntu-classroom-chat | ||
godbyk | Hello, everyone. Welcome to LaTeX for Authors, Editors, and Translators. | 18:01 |
godbyk | You can download the PDF handout from: http://kevin.godby.org/ubuntu-manual/talks/latex-handout.pdf | 18:02 |
godbyk | It has a bit more information than what is contained in the slides, and I will keep it up to date as we add more commands or need to clarify things. | 18:02 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/01.html | 18:02 |
godbyk | In this session, I will be focusing on how you as an author, editor, or translator can help create content for the Ubuntu Manual Project. | 18:03 |
godbyk | We'll start off with a quick overview of LaTeX and I'll try to leave time for questions. | 18:04 |
godbyk | If you have questions, feel free to ask them at any time. Just precede your question with "QUESTION:" | 18:04 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/02.html | 18:04 |
humphreybc | [SLIDE 1] | 18:04 |
humphreybc | BAM! | 18:04 |
godbyk | humphreybc: Nice! | 18:04 |
godbyk | Okay, it looks like we have slides now. | 18:05 |
humphreybc | hehe | 18:05 |
godbyk | Can everyone see the small slide in Lernid? | 18:05 |
godbyk | [SLIDE 2] | 18:05 |
godbyk | [SLIDE 3] | 18:05 |
godbyk | I'll try to keep the web page and the slides in sync in case the slides aren't working for someone. | 18:06 |
godbyk | If you were around during the earlier sessions, you've already heard all about the Ubuntu Manual Project. | 18:06 |
godbyk | But a brief recap: | 18:06 |
godbyk | Our aim is to create a manual in a variety of languages that provides beginners with a good reference for getting started with Ubuntu. | 18:07 |
godbyk | We're using LaTeX to typeset our manual. | 18:07 |
godbyk | [SLIDE 4] | 18:07 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/03.html | 18:07 |
godbyk | LaTeX has been around for over 20 years and is built on top of software that has been around for over 30 years. | 18:08 |
godbyk | Needless to say, it's been bug-tested like nothing else and the underlying TeX engine is often considered to be bug-free. | 18:08 |
godbyk | [SLIDE 5] | 18:09 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/04.html | 18:09 |
godbyk | So what does LaTeX code look like? | 18:09 |
godbyk | Well, the code itself is stored in text files with a .tex extension. | 18:09 |
godbyk | You can use your favorite text editor to write tex files: vim, emacs, gedit, etc. | 18:09 |
godbyk | There are also a number of LaTeX-specific editors out there that provide you with menus that list the LaTeX commands. | 18:10 |
godbyk | For the amount of LaTeX code we're actually using in the Ubuntu Manual Project however, a standard text editor will serve you just fine. | 18:10 |
godbyk | LaTeX code is similar to HTML in that it's a markup language. | 18:11 |
godbyk | So if you want to make text bold in LaTeX, you would use the \textbf command. | 18:11 |
godbyk | Each of the LaTeX commands begins with a backslash (\). | 18:11 |
godbyk | The arguments to the commands are placed inside curly braces { and }. | 18:11 |
godbyk | So if I wanted to make my name bold, I'd write \textbf{Kevin}. | 18:12 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/05.html | 18:12 |
godbyk | [SLIDE 6] | 18:12 |
godbyk | To help us maintain consistency throughout the manual, we'll avoid using the normal "bold", "italics", etc. commands. | 18:13 |
godbyk | Instead we'll use semantic markup. | 18:13 |
godbyk | In LateX, we can define new commands like \menu and \marginnote. | 18:13 |
godbyk | [SLIDE 7] | 18:13 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/06.html | 18:13 |
godbyk | So anytime we want to tell the user about a menu, we can use the new \menu command. | 18:14 |
godbyk | This means that if we decide later that we want all the menus to appear in italics instead of bold, we just have to modify one line of code in the style sheet and not each instance of a menu name throughout the manual. | 18:15 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/07.html | 18:15 |
godbyk | [SLIDE 8] | 18:15 |
godbyk | There are a few special characters in LaTeX that you should be aware of. | 18:15 |
godbyk | In typesetting, we use proper quotation marks (often referred to as "smart quotes"). | 18:15 |
godbyk | The opening quotes are entered using the backtick character. | 18:16 |
godbyk | On US keyboards, this characters is in the upper-left (above the Tab key and next to the 1 key) | 18:16 |
godbyk | It may be in other positions on other keyboards and may not exist at all on some keyboards. | 18:16 |
godbyk | Closing quotation marks are written as two apostrophes. | 18:16 |
godbyk | For the translators, when you're translating from the English to your own language, you can directly enter the quotation marks that you use in your language. | 18:17 |
godbyk | Another set of characters that LaTeX treats special are dashes. | 18:18 |
godbyk | In typesetting there are a variety of dashes that vary in length and are used for different purposes. | 18:18 |
godbyk | LaTeX recognizes these dashes: | 18:18 |
godbyk | There's a hyphen (entered as -), an en dash (entered as --), and an em dash (entered as ---). | 18:19 |
godbyk | In US English, we use the em dash to interrupt thoughts int he middle of a sentence. | 18:19 |
godbyk | Previously in writing the manual content, the rule was to write " --- " (surrounded by spaces). | 18:19 |
godbyk | However, I've recently replaced this with a new \dash command. | 18:19 |
godbyk | This will let us use the proper dashes for each language that we translate to. | 18:20 |
godbyk | So as you're editing the manual, if you come across "---", replace it with the \dash command. | 18:20 |
ClassBot | TomC26 asked: The dash command doesn't have any parameters, it's just "\dash"? | 18:20 |
godbyk | TomC: That's correct. The \dash command doesn't have any parameters, so you just write \dash. | 18:21 |
godbyk | It will handle the spacing around the command as well. | 18:21 |
godbyk | [SLIDE 9] | 18:21 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/08.html | 18:21 |
godbyk | There is more information about the use of the dashes in the handout. | 18:22 |
godbyk | There are another handful of characters that LaTeX uses in its syntax. | 18:22 |
godbyk | If you want these characters to appear in the PDF (and avoid errors from LaTeX), you'll need to precede the characters with a backslash. | 18:22 |
godbyk | So to say, "I ate 50% of the pizza." | 18:23 |
godbyk | you'd have to type: "I ate 50\% of the pizza." | 18:23 |
godbyk | Unfortunately, the backslash character can't be escaped with a backslash, because \\ is actually a command that tells LaTeX to break the line there. | 18:24 |
godbyk | So to get a backslash to appear in the PDF, you'll need to use the \textbackslash command (which doesn't take any arguments). | 18:24 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/09.html | 18:24 |
godbyk | [SLIDE 10] | 18:24 |
godbyk | At this point, the document structure of the manual has been fairly well established. | 18:24 |
godbyk | As you read the .tex files, you'll come across these commands, so I wanted to mention them. | 18:25 |
ClassBot | TomC26 asked: The dash command doesn't have any parameters, it's just "\dash"? | 18:25 |
godbyk | TomC: That's correct. Just \dash. | 18:25 |
godbyk | An example of the \dash command would be: | 18:25 |
godbyk | I like chocolate\dash not vanilla\dash ice cream! | 18:26 |
godbyk | Each of the document structure commands: \part, \chapter, \section, etc. takes a single argument: the name of that part, chapter, section, etc. | 18:27 |
godbyk | To create a new section in the manual, you would write: \section{My New Section} | 18:27 |
ClassBot | humphreybclernid asked: what are the main texlive packages I need to install? | 18:27 |
godbyk | At this point, we require the TeX Live 2009 packages. | 18:28 |
godbyk | Unfortunately, they packages in Karmic are too old. | 18:28 |
godbyk | If you have Lucid, you can install their texlive-* packages and try them out. (I haven't tested them yet.) | 18:28 |
godbyk | Otherwise, you'll need to install TeX Live 2009 without using Ubuntu's repositories. | 18:28 |
godbyk | There are instructions for doing that at the end of the handout. | 18:28 |
ClassBot | humphreybclernid asked: We require the 2009 packages to actually build the english one even? I thought that was just for the translations. | 18:29 |
godbyk | That was correct until a few days ago. But now we require the 2009 version for all languages, including the original English. | 18:29 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/11.html | 18:29 |
godbyk | [SLIDE 11] | 18:29 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/10.html | 18:29 |
godbyk | We can place short notes in the margin. | 18:30 |
godbyk | These notes are used to provide extra information to the reader. | 18:30 |
godbyk | They may contain pointers to other chapters in the manual for more information, links to websites, or additional tidbits of information. | 18:31 |
godbyk | To place text in the margin, use the \marginnote command. | 18:31 |
godbyk | It takes a single argument: the text you wish to appear in the margin. | 18:31 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/11.html | 18:31 |
godbyk | [SLIDE 12] | 18:31 |
godbyk | If you want to include comments in your .tex file, you can write a percent sign (%) and LaTeX will happily ignore any text on that line that appears after the percent sign. | 18:32 |
godbyk | As I mentioned earlier, if you want a percent sign to actually appear in the PDF, you'll have to put a backslash in front of it. | 18:32 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/12.html | 18:32 |
godbyk | [SLIDE 13] | 18:32 |
godbyk | Earlier, I mentioned the \menu command as an example of the semantic markup we're using. | 18:33 |
godbyk | There are a number of commands that we've created to ensure consistency throughout the manual. | 18:33 |
godbyk | First, we'll take a closer look at the \menu command. | 18:33 |
godbyk | The \menu command takes a single argument: the menu, menu item, or list of menus that the user should click on. | 18:34 |
godbyk | However, just to be tricky, inside the argument, you can use the \then command. | 18:34 |
godbyk | This will print a small arrow between each of the menu items. | 18:34 |
godbyk | Another quick note about the \menu command: | 18:35 |
godbyk | In the past, the command was named \nav. This \nav command now redirects automatically to \menu. But if you're editing the manual and see \nav, just replace it with \menu. | 18:35 |
godbyk | Also, there is a \menuitem command that was used in this past. This has also been folded into the \menu command. | 18:36 |
godbyk | Are there any questions about the \menu or \then commands? | 18:36 |
godbyk | Great! I'll move on then. | 18:36 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/13.html | 18:37 |
godbyk | [SLIDE 14] | 18:37 |
godbyk | This is a list of each of the semantic commands we've created so far. | 18:37 |
godbyk | If, as you're editing the manual, you encounter a need for a new command, please let me know and I'll add it. | 18:37 |
godbyk | Most of these commands should be self-explanatory. | 18:37 |
godbyk | They each take a single argument (the name of the GUI element they refer to). | 18:38 |
godbyk | Are there any questions about these commands? | 18:38 |
ClassBot | Wutzara asked: Is there a central place where custom commands are declared - i know a look into the .cls File will do the thing but a place like a Changelog or something never mentiond | 18:38 |
godbyk | Wutzara: Not really. The authoritative source is the .cls file. I will try to keep the handout document updated, though. | 18:39 |
godbyk | Any other questions about anything so far? | 18:39 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/14.html | 18:39 |
godbyk | [SLIDE 15] | 18:40 |
godbyk | Okay, so now for a command that's a bit more advanced. | 18:40 |
godbyk | In the second part of the manual -- the advanced part -- you may have occasion to have the reader use the terminal program. | 18:40 |
godbyk | To print text in a terminal style, we have a "terminal" environment. | 18:41 |
godbyk | Environments are a bit different than commands as they have a begin and end command. | 18:41 |
godbyk | To start the terminal environment, you would write \begin{terminal} | 18:42 |
godbyk | To end the terminal environment, write \end{terminal} | 18:42 |
godbyk | Everything between the \begin and \end lines will be inside the terminal environment and be formatted to look like a terminal. | 18:42 |
godbyk | The \prompt command doesn't take any arguments and prints a user-level BASH prompt ($). | 18:42 |
godbyk | If the user should run the commands as root, you can print a root prompt using the \rootprompt command (which prints a #). | 18:43 |
godbyk | To highlight the text that the user should type themselves, put that text in the argument of the \userinput command. | 18:43 |
godbyk | Are there any questions about the terminal environment or any of the associated commands? | 18:44 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/15.html | 18:44 |
godbyk | [SLIDE 16] | 18:45 |
godbyk | Here are a couple more environments that you'll encounter more often than the terminal environment. | 18:45 |
godbyk | As all environments, they start with \begin and end with \end. | 18:45 |
godbyk | These two environments are for creating different types of lists. | 18:45 |
godbyk | The itemize environment creates a bulleted list. | 18:45 |
godbyk | The enumerate environment creates a numbered list. | 18:45 |
godbyk | (Fancy names, no?) | 18:46 |
godbyk | Each list item starts with the \item command. | 18:46 |
godbyk | Any questions about the list environments? | 18:46 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/16.html | 18:46 |
godbyk | [SLIDE 17] | 18:46 |
godbyk | In a PDF, you can create links to other points in the PDF -- just like a web page. | 18:47 |
godbyk | I've created a couple commands that simplify this linking. | 18:47 |
godbyk | Use the \chaplink command to create a link to another chapter. | 18:47 |
godbyk | Use the \seclink command to create a link to another section in the manual. | 18:47 |
godbyk | Each of those commands takes a single argument: the label of that chapter/section. | 18:48 |
godbyk | To figure out what the label of the chapter/section is, you'll need to open up the .tex file that contains that chapter/section. | 18:48 |
godbyk | Immediately after the \chapter or \section command, you will see a \label command. | 18:48 |
godbyk | The argument to the \label command should match the argument you give to the \chaplink or \seclink command. | 18:49 |
godbyk | All of the chapters have labels assigned already. | 18:49 |
godbyk | Very few of the sections have labels. | 18:49 |
godbyk | If you want to cross-reference a section that doesn't yet have a label, you can add one. | 18:49 |
godbyk | Right after the \section{My section} command, add \label{sec:my-section}. | 18:49 |
godbyk | The chapter labels should start with "ch:" and the section labels should start with "sec:". | 18:50 |
godbyk | The style we use is to write the section name (which may be shortened or abbreviated) with the word separated by hyphens. | 18:50 |
godbyk | Any questions about the cross-referencing commands? | 18:50 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/17.html | 18:51 |
godbyk | [SLIDE 18] | 18:51 |
godbyk | A few notes for translators: | 18:51 |
godbyk | (I'll probably accumulate more of these as we start translating more.) | 18:51 |
godbyk | You should be careful not to translate the LaTeX commands themselves -- only the content of their arguments. | 18:51 |
godbyk | The labels (the argument of the \label, \chaplink, and \seclink commands) shouldn't be translated. | 18:52 |
godbyk | If you're translating to a new language, send me an email to give me a heads-up. | 18:52 |
godbyk | For some of the languages, I have to write new code for LateX to handle that language. | 18:53 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-slides/18.html | 18:53 |
godbyk | [SLIDE 19] | 18:53 |
godbyk | Otherwise, are there any other questions? | 18:53 |
godbyk | For those who are just getting started and need to install LaTeX, I have instructions at the end of the handout. | 18:54 |
godbyk | http://kevin.godby.org/ubuntu-manual/talks/latex-handout.pdf | 18:54 |
ClassBot | konopkov32 asked: How to install Latex 2009? | 18:56 |
godbyk | konopkov: At the end of the handout (http://kevin.godby.org/ubuntu-manual/talks/latex-handout.pdf), there are instructions for downloading and installing TeX Live 2009. | 18:57 |
godbyk | The installation script is fairly straight-forward. | 18:57 |
godbyk | One caveat: The full installation of TeX Live 2009 is about a 2 GB download, so it may take a while. | 18:57 |
godbyk | You can install less than the full set of packages, though. | 18:57 |
godbyk | You'll need to make sure that you've selected the XeLaTeX (or XeTeX) engine, and the language you want to compile the document in. | 18:58 |
ClassBot | gsmx asked: are there better editors than just gedit? | 18:58 |
godbyk | gsmx: Sure! | 18:58 |
godbyk | If you already have a favorite text editor, you can use that. | 18:58 |
godbyk | If you want something a little fancier -- an IDE for LaTeX, of sorts -- you can use Kile (for KDE) or TeXMaker for GNOME. | 18:58 |
godbyk | There are other LaTeX editors as well. | 18:59 |
godbyk | I would recommend compiling the document with the 'make' command, however, as the editors may not know how to handle the translations. | 18:59 |
godbyk | Unfortunately, the fancy edits won't know about our Ubuntu Manual--specific commands like \menu, \chaplink, etc. So it may not successfully auto-complete those for you. | 19:00 |
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Using Launchpad to manage the project - Instructor: humphreybc || Questions in #ubuntu-classroom-chat | ||
godbyk | Are there any final questions about LaTeX? | 19:00 |
godbyk | If you run into problems or have questions later, I'm usually in the #ubuntu-manual channel. Feel free to pester me there or email the ubuntu-manual mailing list. | 19:01 |
humphreybc | cool | 19:01 |
humphreybc | should we start up the launchpad session now? | 19:01 |
humphreybc | [SLIDE 1] | 19:01 |
humphreybc | http://launchpad.net/ubuntu-manual | 19:02 |
humphreybc | okay everyone see the slides? | 19:03 |
humphreybc | you can download them from here if you can't: http://kevin.godby.org/ubuntu-manual/talks/launchpad.pdf | 19:04 |
humphreybc | So basically if you haven't been using Launchpad for long, you might be unfamiliar with what it does and how it works | 19:05 |
humphreybc | Basically launchpad is a website that provides tools for international project management | 19:05 |
humphreybc | we use it for pretty much everything in UMP | 19:05 |
humphreybc | (btw if people want to ask a question, just use "question:" | 19:06 |
humphreybc | [SLIDE 2] | 19:06 |
humphreybc | Ground Control / bazaar interfaces with Launchpad to download and upload code | 19:06 |
humphreybc | the code is hosted in branches on launchpad | 19:07 |
humphreybc | Launchpad also provides many project planning and management features, such as blueprints and milestones | 19:07 |
humphreybc | It also provides a tool for bugs, a tool for translations and a tool that allows people to ask questions about the project | 19:07 |
humphreybc | For things like committing to the branch or translating, you'll need to be in the correct team | 19:08 |
humphreybc | to join the team, you just need to visit our team page: https://launchpad.net/~ubuntu-manual | 19:08 |
humphreybc | For the translations, usually a translation team, loco team or our team should work | 19:08 |
humphreybc | Our team is a public team which means anyone with a launchpad account can join | 19:09 |
humphreybc | [SLIDE 3] | 19:09 |
humphreybc | https://code.launchpad.net/ubuntu-manual | 19:09 |
humphreybc | Launchpad uses branches to manage code | 19:09 |
humphreybc | most projects have many different branches for different people, and those people submit "merge proposals" to get into the main branch. | 19:10 |
humphreybc | But because we are a big project with a lot of contributors and a short time period to complete the project, we don't bother with merge proposals | 19:10 |
humphreybc | this means that members of the team can push directly into main | 19:10 |
humphreybc | Launchpad keeps track of each revision | 19:11 |
=== zebrapig is now known as zebrapiggy | ||
humphreybc | and when you commit, you give a short description of what you've changed, which appears beside the revision number | 19:11 |
humphreybc | https://code.launchpad.net/~ubuntu-manual/ubuntu-manual/main | 19:11 |
humphreybc | this is the main branch | 19:12 |
humphreybc | if you scroll down, you'll see the latest revision was 297 | 19:12 |
humphreybc | [SLIDE 4] | 19:12 |
humphreybc | Blueprints | 19:12 |
humphreybc | https://blueprints.launchpad.net/ubuntu-manual | 19:13 |
humphreybc | blueprints are specifications or plans for features that we want to implement in the project | 19:13 |
humphreybc | they let us break down the overall project into small parts, and tell us a number of things about each part | 19:13 |
humphreybc | not only do they explain what the feature needs to do, but also who's going to work on it, how long it'll take, when it should be ready and what progress is being made | 19:14 |
humphreybc | we can target blueprints towards milestones | 19:14 |
humphreybc | blueprints also give us an option to choose a priority | 19:14 |
humphreybc | in our project, essential is reserved for things that are essential to the success of the project | 19:14 |
humphreybc | ie, without a latex template, we wouldn't even have a document at all | 19:15 |
humphreybc | high priority is usually given to chapters, ie, the content | 19:15 |
humphreybc | you can assign yourself to a blueprint | 19:15 |
humphreybc | but most of them are already taken | 19:16 |
humphreybc | [SLIDE 5] | 19:16 |
humphreybc | https://launchpad.net/ubuntu-manual/+milestones | 19:16 |
humphreybc | Milestones | 19:16 |
humphreybc | In our project, our milestones are the releases | 19:16 |
humphreybc | each release has a release date | 19:17 |
humphreybc | we are currently in the alpha release stage | 19:17 |
humphreybc | and are working towards the beta release - which will come out on March 18th. | 19:17 |
humphreybc | because our branch is a _rolling branch_ a release doesn't really amount to a lot of new things all at once | 19:17 |
humphreybc | it's just something to target and aim for | 19:17 |
humphreybc | blueprints are targeted to milestones | 19:17 |
humphreybc | [SLIDE 6] | 19:18 |
humphreybc | Bugs | 19:18 |
humphreybc | https://bugs.launchpad.net/ubuntu-manual | 19:18 |
humphreybc | Anyone can report a bug, you don't have to be a member of a team | 19:18 |
humphreybc | You only have to have a launchpad account | 19:18 |
ClassBot | gsmx asked: Why aren't the translations targeted in one of the milestones? | 19:19 |
humphreybc | Excellent question. Because I haven't created a blueprint for translations yet, I've forgotten :D | 19:19 |
humphreybc | We are actually targeting the translations to RC | 19:19 |
humphreybc | So as you can see, we have a few bugs there | 19:20 |
humphreybc | when reporting a bug, try to include things like the error message, or the page you saw the bug on etc | 19:20 |
humphreybc | so we can fix it easily | 19:20 |
humphreybc | also the revision number you encountered the bug on | 19:20 |
humphreybc | you can report anything as a bug, from latex technical stuff to factual errors and spelling mistakes | 19:21 |
humphreybc | Quickshot bugs should be reported on the quickshot project page (it has it's own project page and team) | 19:21 |
humphreybc | [SLIDE 7] | 19:21 |
humphreybc | https://translations.launchpad.net/ubuntu-manual | 19:21 |
humphreybc | I won't talk too much about translations, because dutchie has an entire session on them | 19:22 |
humphreybc | Basically we use a program called po4a that takes the information from the .tex files and turns it into .po and .pot files that launchpad can read | 19:22 |
humphreybc | click on "View all languages" under the "Translation for main" heading to see all the translations | 19:23 |
humphreybc | as you can see there are quite a lot | 19:24 |
humphreybc | dutchie is presenting translations next | 19:24 |
humphreybc | so you can learn some more about them :) | 19:24 |
humphreybc | [SLIDE 8] | 19:25 |
humphreybc | https://answers.launchpad.net/ubuntu-manual | 19:25 |
humphreybc | Here you can ask questions about the project | 19:25 |
humphreybc | anything you want to know | 19:25 |
humphreybc | and we'll try to answer them as soon as possible | 19:25 |
humphreybc | [SLIDE 9] | 19:26 |
=== montel is now known as Guest40565 | ||
humphreybc | I don't think there is a slide 9... :P | 19:26 |
humphreybc | Questions? | 19:26 |
humphreybc | Nobody has any questions on Launchpad? | 19:27 |
humphreybc | i'll show you something cool then | 19:27 |
humphreybc | https://launchpad.net/~ubuntu-manual/+map | 19:27 |
humphreybc | check out the team member locations | 19:28 |
humphreybc | dutchie: indeed! | 19:28 |
ClassBot | konopkov32 asked: Should I use Launchpad or .po files directly to translate? | 19:28 |
humphreybc | You should use launchpad to translate | 19:28 |
humphreybc | but dutchie will explain more soon | 19:29 |
humphreybc | I think it shouldn't matter if you translate from the po files directly | 19:29 |
humphreybc | https://launchpad.net/~ubuntu-manual/+mugshots | 19:29 |
humphreybc | you can check out all the pretty people that make up our project! | 19:29 |
humphreybc | http://www.facebook.com/pages/The-Ubuntu-Manual/266794861575?ref=ts | 19:32 |
humphreybc | you guys should join our facebook page | 19:32 |
humphreybc | 183 fans now! | 19:32 |
humphreybc | anyone need help setting up a launchpad account or ssh key? | 19:34 |
humphreybc | or using Ground Control? | 19:34 |
humphreybc | http://twitter.com/TheUbuntuManual | 19:34 |
humphreybc | aaaand my HTC Magic Android phone just arrived | 19:36 |
humphreybc | right i'm gonna bugger off for the rest of this session and play with my new cell! | 19:36 |
humphreybc | cool so that's all, i'll be back at 2100 UTC | 19:39 |
humphreybc | :) | 19:39 |
humphreybc | i'll keep my head in your talk tho dutchie | 19:40 |
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Translations and how they work - Instructor: dutchie || Questions in #ubuntu-classroom-chat | ||
dutchie | here we go then | 20:00 |
dutchie | Hi everyone, and welcome to my talk on the translations system used by the Ubuntu Manual project. | 20:00 |
dutchie | My name is Josh Holland, and I go by the nick dutchie. | 20:01 |
dutchie | (as you can probably see) | 20:01 |
dutchie | I've been involved in the Ubuntu Manual project since pretty much the beginning. | 20:01 |
dutchie | I run a fair bit of the backend stuff, including the IRC bot, the planet, and, of course, the translations. | 20:01 |
dutchie | What I'm going to cover today includes: | 20:01 |
dutchie | * How to contribute a translation | 20:01 |
dutchie | * A brief overview of the translation infrastructure | 20:01 |
dutchie | * How to build a translated version of the manual | 20: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. | 20:01 |
dutchie | I'll also pause for questions at the end of each section. | 20:01 |
dutchie | So, let's get started! | 20:02 |
dutchie | (I hope nobody has any questions so far :) ) | 20:02 |
dutchie | [How to contribute a translation] | 20:02 |
dutchie | This is easy! Just go to http://translations.launchpad.net/ubuntu-manual and click on the language you want to translate. | 20:02 |
dutchie | ooh, I forgot to mention, I don't have any slides | 20:02 |
dutchie | sorry if you need pretty things to look at, you're stuck with text for this one | 20:03 |
dutchie | You will then see the Launchpad translations UI. | 20:03 |
dutchie | All you have to do now is enter your translations into the boxes | 20:03 |
dutchie | They will then be reviewed, and hopefully included in the final translation! | 20:03 |
dutchie | Any questions so far? | 20:03 |
dutchie | [The translation infrastructure] | 20:04 |
dutchie | The Ubuntu Manual and Launchpad use the GNU Gettext system of translations | 20:04 |
dutchie | This is centred around two types of file: .pot files and .po files. | 20:04 |
dutchie | .pot files are translation template files, and contain all of the strings that need translation | 20:04 |
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 | 20:05 |
dutchie | you can see them at http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/main/files/head:/po/ | 20:06 |
dutchie | The .po files are the ones which actually contain the translations | 20:06 |
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 | 20:06 |
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 | 20:06 |
dutchie | But basically, the .po files contain the untranslated string and the translated string next to each other in a nice parsable format | 20:07 |
dutchie | GNU Gettext is mainly intended to translate software programs, rather than documentation | 20:07 |
dutchie | We therefore can't use it directly, becuase it is normally used as a software library | 20:08 |
dutchie | So, in Python for example, you'd do "import gettext" and mark each string for translation by passing it to a function | 20:08 |
dutchie | Other major languages work in much the same way | 20:09 |
dutchie | Instead, we use po4a, or po for anything (http://po4a.alioth.debian.org) | 20:09 |
dutchie | This is a set of Perl scripts that allow you to use the infrastructure built up around translating Gettext files for your project | 20:09 |
dutchie | This infrastructure includes Launchpad's excellent Rosetta system, Emacs's po mode, and GUI tools like poedit | 20:10 |
dutchie | It supports manpages, Perl pod format, xml, sgml, TeX, plain text, ini and KernelHelp files | 20:10 |
dutchie | Obviously, we're interested in the TeX bit, since LaTeX is a dialect of TeX | 20:11 |
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 | 20:11 |
dutchie | po4a reads the configuration file and works out which files to read, and where to put the translated versions | 20:12 |
dutchie | Ours is visible at http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/main/annotate/head:/po4a.conf | 20:12 |
dutchie | It's quite small :) | 20:12 |
dutchie | And also pretty self-explanatory | 20:12 |
dutchie | Note how I don't need to tell it all the individual files, it reads the main.tex file and works out for itself that the chapters need to be read individually | 20:13 |
dutchie | Any questions on Gettext or po4a? | 20:13 |
dutchie | OK, moving on then | 20:16 |
dutchie | [How the translations are updated] | 20:16 |
dutchie | I try to update the translations around every day. | 20:16 |
dutchie | However, I have a busy life and I don't always manage this, so be gentle if I forget ;) | 20:16 |
dutchie | There are two stages to updating the translations. | 20:16 |
dutchie | 1. Updating the translated files | 20:16 |
dutchie | (So we pull in any new translations from launchpad) | 20:17 |
dutchie | 2. Updating the translation .pot file | 20:17 |
dutchie | This may also involve changing the .po files, if some text has been added, taken away or changed | 20:17 |
dutchie | The translations done on Launchpad are exported into the lp:~jshholland/ubuntu-manual/manual-trans branch | 20:18 |
dutchie | Launchpad allows for a fair bit of automation in this area | 20:18 |
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. | 20:18 |
dutchie | Note that this means that the translations on Launchpad are considered the definitive version | 20:19 |
dutchie | If you've made a change to the po file directly in the branch, it's possible that it will be overwritten by someone else's translation on LP | 20:19 |
dutchie | However, Launchpad does scan the branch when it's uploaded, so it could still be used in the final product | 20:20 |
dutchie | This is me encouraging people not to change the files directly, but do so if the Rosetta interface *really* annoys you | 20:21 |
ClassBot | spiral53 asked: what happens if in the english source file, a sentence changes, how do you know which sentence in the translation has to change? | 20:21 |
dutchie | Good question | 20:21 |
dutchie | This is what po4a is designed to handle | 20:21 |
dutchie | It scans the LaTeX source and checks the files for changes | 20:22 |
dutchie | It's very clever, I don't really understand the guts of it :) | 20:22 |
dutchie | The text in the .pot and .po files is indexed by filename and line number too | 20:23 |
dutchie | so that helps tools like po4a keep track of what's going on | 20:23 |
dutchie | That answer your question? | 20:23 |
dutchie | < spiral53> so you are supposed to translate it as much like the original as possible with regards to sentence order | 20:24 |
dutchie | It's up to you as a translator to keep the spirit and flow of the manual in your language | 20:25 |
dutchie | The text is translated in paragraph-sized chunks, so there is some scope for moving sentences around | 20:25 |
dutchie | Do whatever you have to to keep the manual well-written and in a sensible order | 20:25 |
dutchie | OK, carrying on then | 20:26 |
dutchie | Once I've done this, I commit the merge and run the following command: | 20:26 |
dutchie | (this is a big one) | 20:26 |
dutchie | $ po4a --no-translations --copyright-holder="The Ubuntu Manual Team" --package-name=ubuntu-manual --package-version=$(bzr version-info --custom --template={revno}) po4a.conf | 20:26 |
dutchie | This command updates the .pot file and .po files, without generating translated content, and sets appropriate values in the files. | 20:26 |
dutchie | You don't really have to worry about what this does or how it does it, but this is what I do to keep things up-to-date | 20:27 |
dutchie | This is then committed and the whole lot is pushed up to Launchpad. | 20:27 |
dutchie | Launchpad then scans the branch, and imports the .po and .pot files to use as a basis for the translations done. | 20:27 |
dutchie | Launchpad is really quite clever in this sort of area | 20:27 |
dutchie | Every time a new commit is pushed, it goes through the source tree and imports any new or changed translations into Rosetta | 20:28 |
dutchie | The cycle then repeats. | 20:28 |
dutchie | Any questions about how this all works? | 20:29 |
dutchie | OK, while you're all mulling that over, I'll talk a bit about freezes | 20:29 |
dutchie | (Nothing to do with the weather, even if it has been cold) | 20:30 |
dutchie | Early on, when lots and lots of content was being written and changed around, we had a few problems with translations | 20:30 |
dutchie | People would translate a phrase, which would then be changed a day or two later to something else, and it'd need translating again | 20:31 |
dutchie | This is less of a problem now, as the vast majority of the content is now written, and unlikely to change further, but it still happens to some extent | 20:32 |
dutchie | To give the translators a chance to catch up with what's been written, we intend to freeze the writing around the beta | 20:32 |
dutchie | At this point, we'd stop writing and editing content, and focus on getting screenshots and translations done | 20:33 |
dutchie | Does this make sense to everyone? | 20:33 |
ClassBot | komsas_ asked: what to do with strings laike that "For example in (year????), Dell began a collaboration" ? | 20:34 |
dutchie | In places like that, we haven't got the exact date we need for that | 20:34 |
dutchie | So, for now translate it in a way that suggests it will be filled in later | 20:35 |
dutchie | That is the sort of thing we'd want sorted out for the beta | 20:35 |
ClassBot | spiral53 asked: What happens if the translated text is longer than the english one, and screenshots doesn't fit any more as they are supposed to. | 20:36 |
dutchie | LaTeX should be intelligent enough to deal with cases like that, though you'd have to ask godbyk to be sure | 20:36 |
dutchie | I'm fairly certain that it wouldn't really be a problem | 20:36 |
dutchie | Any further questions before I move on? | 20:37 |
dutchie | [How to build a translated version of the manual] | 20:38 |
dutchie | (This next bit applies mostly to before you had to be running Tex Live 2009 anyway, so I'll skip through it quickly) | 20:38 |
dutchie | Thanks to some cool work from godbyk, our LaTeX guru, it's not too hard to see your translations in the manual. | 20:38 |
dutchie | Unfortunately, we've had to use the polyglossia LaTeX package to handle the translations. | 20:38 |
dutchie | This is only available with texlive 2009, which is only in the repos for Lucid (10.04). | 20:38 |
dutchie | So, if you're running Karmic (9.10), you have two choices: | 20:38 |
dutchie | 1. Upgrade to Lucid | 20:38 |
dutchie | 2. Download and install texlive 2009 directly from upstream | 20:38 |
dutchie | This set of instructions was taken from https://lists.launchpad.net/ubuntu-manual/msg00548.html (thanks godbyk) | 20:39 |
dutchie | The first part of this will only apply to people running Karmic (or earlier). | 20:39 |
dutchie | Step one is removing any texlive packages you've already got. | 20:39 |
dutchie | You can do this on the command line via "sudo apt-get remove texlive-*" or through Synaptic. | 20:39 |
dutchie | The next step is to download http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz, the install script for texlive | 20:39 |
dutchie | You can then unpack the tarball by "tar -xvvzf install-tl-unx.tar.gz" and change into the newly unpacked directory | 20:39 |
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!) | 20:39 |
dutchie | This will take quite a while, so be patient. | 20:39 |
dutchie | Once this is done, change into the ubuntu-manual directory, and run pkgs/install-pkgs.sh script | 20:39 |
dutchie | That's the Karmic-specific stuff out of the way. Lucid folks can just install texlive-base. | 20:39 |
dutchie | It should hopefully find everything; if it doesn't, and you're on Lucid, it's safe to install the suggested ones | 20:39 |
dutchie | If you're on Karmic, however, something has gone wrong with the installation. | 20:39 |
dutchie | Drop into #ubuntu-manual and we'll try and help you out. | 20:39 |
dutchie | So now you've got all the texlive 2009 packages installed, you can build the manual. | 20:39 |
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. | 20:39 |
dutchie | Ignore that lot and listen to godbyk :) | 20:39 |
dutchie | So, once you've got everything installed, you can (as it says there) just "make ubuntu-manual-LANG.pdf" | 20:40 |
dutchie | All being well, the manual will now build, and you can see the fruits of your labour | 20:40 |
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- | 20:40 |
dutchie | If you have any problems in that sort of area, again ask godbyk | 20:40 |
dutchie | He's the one in charge of LaTeXy stuff :) | 20:40 |
dutchie | Any questions on that? | 20:41 |
dutchie | That's pretty much all I have to say about translations. | 20:41 |
dutchie | I hope this has helped you to understand how the translations, and maybe do some translations for yourself! | 20:41 |
dutchie | Thanks a lot for coming along. | 20:42 |
dutchie | Any questions to fill up this 20 minutes I've got left over now? | 20:42 |
dutchie | OK, there don't seem to be any questions, so I'll leave it there | 20:44 |
ClassBot | komsas_ asked: Will be pdf version for all languages, I think it will be more easy for all translators. | 20:45 |
dutchie | Of course there will! | 20:45 |
dutchie | No point translating it if we then don't build a final version out of the translations :) | 20:46 |
dutchie | I think we're done for real now ;) | 20:46 |
dutchie | If you have any more questions or problems, I'm usually around in the #ubuntu-manual channel, or you can send an email to the mailing list | 20:47 |
dutchie | ubuntu-manual@lists.launchpad.net | 20:47 |
ClassBot | c7p asked: Which language's pdf will be available on lucid's live-cd ? i mean how many is it possible to contain? | 20:47 |
dutchie | Stop coming up with these just as I think I'm finished :) | 20:48 |
dutchie | Getting the manual on the live CD is looking unlikely at the moment | 20:48 |
dutchie | Understandably, Canonical and the core developers don't want to put so much public backing to such a new project | 20:49 |
dutchie | What we've got to do is get a really good manual, in lots of different languages, to show that we can deliver the goods | 20:49 |
dutchie | Then we've got to do it all again for Lucid+1 :) | 20:49 |
=== william is now known as Guest60543 | ||
dutchie | Even if we do show we're up to the standard, it's not a small file to be putting onto the live cd | 20:51 |
dutchie | At the moment, it's 1.2M, and that's without screenshots | 20:52 |
dutchie | A CD is only 700M, and there's a great distro to go on there first :) | 20:52 |
dutchie | I personally can't see translated versions being put on the live cd | 20:52 |
dutchie | I think some LoCos do respins for their area, and they may well consider it | 20:53 |
dutchie | I'm sure that an Ubuntu DVD is on the cards for the near future too | 20:53 |
dutchie | Plenty of room on there for a little PDF manual :) | 20:53 |
dutchie | I think I am actually done now | 20:57 |
dutchie | Thanks everyone for keeping me on my toes with good questions | 20:57 |
dutchie | Now go and get translating! | 20:57 |
dutchie | Next up is humphreybc to talk about social media then | 20:58 |
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: The project and social media - Instructor: humphreybc || Questions in #ubuntu-classroom-chat | ||
humphreybc | right | 21:01 |
humphreybc | sorry distracted by andriod phone :P | 21:01 |
humphreybc | how did the presentation go dutchie? | 21:01 |
humphreybc | [SLIDE 1] | 21:01 |
humphreybc | http://www.facebook.com/pages/The-Ubuntu-Manual/266794861575?ref=ts | 21:01 |
humphreybc | okay | 21:02 |
humphreybc | so social media | 21:02 |
humphreybc | it's important to us | 21:02 |
humphreybc | why is it important to us? | 21:02 |
humphreybc | [SLIDE 2] | 21:02 |
humphreybc | social media increases publicity and hype for projects | 21:02 |
humphreybc | the ubuntu manual project wouldn't be anywhere near it is now if it wasn't for blogging sites | 21:03 |
humphreybc | facebook has been helpful too | 21:03 |
humphreybc | and so has twitter | 21:03 |
humphreybc | not just our own pages, but also other people retweeting things | 21:03 |
humphreybc | social media encourages more people to help and get involved | 21:03 |
humphreybc | they feel "important" if you will, because the project they are working on is in the limelight | 21:04 |
humphreybc | it's much more rewarding to see a project that you're working on all over the internet and blog sites, than it is to see nothing about a project you're working on | 21:04 |
humphreybc | media attention and hype also puts pressure on our project to live up to the hype | 21:04 |
humphreybc | pressure is good for projects, especially with ambitious projects like our own | 21:05 |
humphreybc | it makes our contributors work harder and do better, knowing that a) they'll let a lot of people down if they don't live up to the hype and b) when the project is released, they'll get a good chunk of credit for it | 21:05 |
humphreybc | social media also spreads the word about our project | 21:05 |
humphreybc | and it doesn't just spread the word for help | 21:05 |
humphreybc | it also makes people aware of the manual | 21:06 |
humphreybc | so we're going to have a lot of people actually download it and read it simply because they know about it | 21:06 |
humphreybc | so many projects are awesome but undiscovered, we never hear about them | 21:06 |
humphreybc | what's the point in writing a 200 page manual if no one sees it? | 21:06 |
humphreybc | [SLIDE 3] | 21:06 |
humphreybc | So, it is natural for us to use social media and "web 2.0" to our advantage | 21:06 |
humphreybc | we have created a facebook, twitter and identi.ca accounts | 21:07 |
humphreybc | we also have an aggregated blog planet | 21:07 |
humphreybc | i'll run through these now | 21:07 |
humphreybc | Facebook: | 21:07 |
humphreybc | you can see the facebook page in the window in lernid | 21:07 |
humphreybc | for those not using lernid: http://www.facebook.com/pages/The-Ubuntu-Manual/266794861575?ref=ts | 21:07 |
humphreybc | we have 187 fans apparently | 21:07 |
humphreybc | Facebook is good because it allows us to post updates on the progress, generate hype for events such as this, and also plan events where people can RSVP to them | 21:08 |
humphreybc | also people can ask questions and discuss in the group forum | 21:08 |
humphreybc | it gets people talking about our project | 21:08 |
humphreybc | gets people excited | 21:08 |
humphreybc | and that's what we've been riding on these past two months, a huge wave of excitement and hype surrounding this awesome *new* and *fresh* project for ubuntu | 21:09 |
humphreybc | we may not be as crucial as the boot team changing to plymouth, or as exciting as the MeMenu | 21:09 |
humphreybc | but those projects haven't got a facebook group, they don't have an aggregated blog or a twitter account where you can actively see the progress | 21:09 |
humphreybc | they aren't _transparent_ - they don't communicate with the users enough | 21:09 |
humphreybc | and hence we never hear about them, and they probably say with only half a dozen contributors for the majority of their lifespan | 21:10 |
humphreybc | of course, some people don't want 250+ people in their team | 21:10 |
humphreybc | some projects don't need that many people | 21:10 |
humphreybc | but having more people = more ideas and more features | 21:10 |
humphreybc | it also allows us to have a greater input from everyday users | 21:10 |
humphreybc | so we come out overall with a better product | 21:10 |
humphreybc | http://twitter.com/TheUbuntuManual | 21:11 |
humphreybc | Our twitter account | 21:11 |
humphreybc | 118 followers | 21:11 |
humphreybc | http://identi.ca/theubuntumanual | 21:11 |
humphreybc | (I don't know much about identi.ca because I don't use it) | 21:12 |
humphreybc | but even then, 30 subscribers | 21:12 |
humphreybc | and this is for a team creating a book! | 21:12 |
humphreybc | people obviously like what we're doing and feel the manual is needed in ubuntu | 21:12 |
humphreybc | but had we not been so aggressive in publicising it, i don't think we'd be anywhere near where we are | 21:12 |
humphreybc | and I think it's important for projects of any kind to get out there and show people what they're doing, make it easy for people to contribute, and be transparent, talk to the users and ask them what they want. Hold meetings regularly, run events like these where people can see what it's all about | 21:13 |
humphreybc | http://planet.interesting.co.nz | 21:13 |
humphreybc | The Ubuntu Manual Planet (courtesy of dutchie) | 21:13 |
humphreybc | Once again, an "insight into the lives of UM developers" | 21:14 |
humphreybc | [SLIDE 4] | 21:14 |
humphreybc | So, with all that in mind - how can you help with social media for the UMP? | 21:14 |
humphreybc | if you haven't already found something to do from the other presentations | 21:15 |
humphreybc | we still need people to actively maintain things like the facebook and twitter accounts, identi.ca etc | 21:15 |
humphreybc | update the screenshots on facebook, change the logo on twitter, tweet new things in the manual, new revisions, progress | 21:15 |
humphreybc | and also spread it so your family and friends can join | 21:15 |
humphreybc | obviously only if they're interested :P | 21:15 |
humphreybc | UMP, although voluntary, can be used as experience on a resume | 21:16 |
humphreybc | employers value work in the open source community | 21:16 |
humphreybc | so if you are in IT, there are benefits for you | 21:16 |
humphreybc | working with UMP can lead to ubuntu membership, UDS sponsorship, credit in the community, other projects, meeting people, even canonical employment! | 21:16 |
humphreybc | And anything you do, big or small, will be included in the credits | 21:16 |
humphreybc | So, in summary: More projects should use social media to their advantage to spread the word, generate hype, get more contributors, more feedback and ideas, and overall a better product. | 21:17 |
humphreybc | Questions? | 21:17 |
humphreybc | komsas_ asked: " what you can suggest for other Loco teams, how to attract more contributors (translating, editing etc.)?" | 21:18 |
humphreybc | Well, I would start by creating a facebook group to attract people from your country and networks | 21:19 |
humphreybc | you can also run events and things through it | 21:19 |
humphreybc | then come up with cool ideas for events that you can run | 21:19 |
humphreybc | and tell ubuntu members about them so they can post on the planet | 21:19 |
humphreybc | email blogs | 21:19 |
humphreybc | and the forums | 21:19 |
humphreybc | hold a survey on the forums and email the forum council to see if they could feature it | 21:20 |
humphreybc | perhaps attach your loco to a project to ride off their publicity | 21:20 |
humphreybc | and make sure there are lots of things to do across a wide range of areas | 21:20 |
humphreybc | create jobs for people if you don't have any | 21:20 |
humphreybc | and when you come across someone willing to help, treat them as if they are very important | 21:21 |
humphreybc | they'll appreciate it and they'll be even more willing to help | 21:21 |
humphreybc | value their feedback and ideas | 21:21 |
humphreybc | :) | 21:21 |
humphreybc | tom, that's a good suggestion | 21:22 |
ClassBot | jorgetb asked: I would like to help the team, how can I start to help? | 21:22 |
humphreybc | have you been around for the other sessions? | 21:23 |
humphreybc | what are you interested in? what are you skills? ie, programming, artwork, writing, translating? | 21:23 |
humphreybc | cool, well we need writers and translators! | 21:24 |
humphreybc | start by jumping over to #ubuntu-manual on irc | 21:25 |
humphreybc | and also email the mailing lists with some of your talents or what you're interested in | 21:25 |
humphreybc | mailing list* | 21:25 |
humphreybc | that way we can find out what you like to do best and get you doing what you want | 21:25 |
humphreybc | no problem jorgetb :) | 21:26 |
humphreybc | i'm normally around in IRC and you can also email me whenever you want, humphreybc@gmail.com | 21:26 |
humphreybc | find me on facebook too :) | 21:26 |
ClassBot | TomC asked: What do you think of having members of the UM team attending Lucid release parties, wherever they may be held? | 21:27 |
humphreybc | Tom, great idea! | 21:27 |
humphreybc | UM members and contributors should definitely go along to the release parties and spread the word about the manual | 21:27 |
humphreybc | while the people at the release parties are probably not the target audience for us, everyone likes getting free documentation and free stuff | 21:27 |
humphreybc | we might get some new contributors that way too :) | 21:28 |
humphreybc | any other questions? | 21:28 |
humphreybc | okay well thanks to everyone for coming, if you missed any of the sessions you can find them again on irclogs.ubuntu.com | 21:29 |
humphreybc | the slides are in the bzr branch and also on kevin's website: http://kevin.godby.org/ubuntu-manual/talks | 21:30 |
humphreybc | and my ground control demo: http://www.youtube.com/watch?v=MeNXqfofbWk | 21:30 |
humphreybc | we're repeating the sessions again later on, they start up at 0400 UTC I believe | 21:30 |
humphreybc | so if you missed one in particular and want to come along, you've got another chance :) | 21:30 |
humphreybc | https://wiki.ubuntu.com/ubuntu-manual | 21:31 |
=== epkugelmass is now known as Guest86761 | ||
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi | ||
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Current Session: Test - Instructor: cjohnston || Questions in #ubuntu-classroom-chat | ||
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi |
Generated by irclog2html.py 2.7 by Marius Gedminas - find it at mg.pov.lt!