Response to an Ubuntu Manual Critique

Robin Catling wrote a great critique of the first edition of Getting Started with Ubuntu 10.04. I wanted to respond to a few of his points and didn’t want to constrain myself to a small comment on his blog.

Who are we aiming this at—who is in our intended audience?

Our idea of the audience for our manual is admittedly not very well-defined at the moment. It’s something we’re working to improve. Currently, we assume our audience has basic computer skills (e.g., they know how to use a mouse and keyboard and they have a basic understanding of the concepts of windows, menus, etc. and how to manipulate them). While we occasionally make references to Windows and Mac OS X software that is analogous to the Ubuntu software we’re discussing, we don’t rely on any explicit knowledge of that software. Our audience isn’t defined much beyond these basic assumptions, though.

165 pages is still too intimidating a length for ‘Getting Started’

I’m not worried about the length at this point, only the content. However, we’re planning on making our writing more concise and culling out some material for the Maverick edition. We will likely take much of the advanced material (such as the introduction to the terminal) and provide it in an online-only format (or gathered together in a separate manual).

The prologue indicates very conventional computer-manual thinking. You just lost half your audience. Be more radical. The Dummies books were onto something. Go further.

Thank you for the encouragement to be more bold. I have some ideas to help us break out of the typical ‘step-by-step instructions’ and ‘slog through all this boring stuff to find the bits you care about’ forms of computer manuals. I’m currently gathering my thoughts on this and doing a bit of research. I’ll be pitching my ideas soon.

How many of the audience groups listed above give a flying #### about ‘the philosophy of Ubuntu’?

I agree wholeheartedly. We will be rearranging this material in future editions so that it’s more supplemental and not the first thing a reader encounters upon opening the book.

Consider re-ordering the contents and lifting some to Appendices in back.

We will be revisiting this in our Maverick edition. If you have any specific recommendations, I’d love to hear them.

Give me a nice friendly map of the manual at the front. Maybe even a flowchart so I can evaluate what kind of user I am and therefore where I should start.

I’m not sure a flowchart qualifies as a ‘friendly map’, but I take your point. We should add some text to the prologue that serves as a roadmap to the remainder of the manual.

Consider task-oriented layout, what do I as user need to achieve.

I think a task-oriented organization structure is great for system help where people can look up step-by-step instructions to complete a particular task. A book, though, better lends itself to goal-oriented projects and more longer-term learning experiences.

Instead of presenting step-by-step instructions for, say, scanning a photo using Simple Scan, we could provide instructions and tutorials on creating a great-looking birthday card that incidentally requires the reader to learn how to scan the photo, touch it up (to remove red eye, crop it to the appropriate size, etc.), install a funky font, pull the photo into Inkscape, lay it out on the page, set up her printer to use the special card stock she bought just for the occasion, etc.

The goal-oriented approach shows the reader how to accomplish awesome things using Ubuntu and its applications. The goals consist of multiple tasks and helps keep the reader engaged—now they’re doing something realistic and that has direct application to their life—not simply reading through a series of steps to set up a printer.

This format is completely different than most computer manuals take. I’m going to work with the docs team, learning team, and manual team to see where this type of instruction fits in the Ubuntu documentation ecosystem.

Most people will use the PDF on-screen. Put it in landscape and 2- or 3-column. I’m scrolling too much.

This may be true. For on-screen instructions, we’re going to provide an HTML version for Maverick. And, as always, there is still the existing system help.

This manual was designed from the beginning to be a printed book and that’s what the design focuses on. Some concessions were made to improve on-screen readability, but there are better formats than PDF for that purpose.

Putting the text in two columns means that the reader would have to scroll twice as much: down the first column, then back up to read the second column.

That font just plain hurts my eyes.

Thorsten Wilms and I spent quite a bit of time exploring the open fonts that were available to us. We discovered that most of the open fonts had lousy kerning or poor glyph coverage (for supporting non-English languages). The typeface we chose for the body text (Linux Libertine by Philipp H. Poll) has great language support for Latin-based scripts, Greek, Hebrew, and Cyrillic. In addition, it has a nice italic, an unobtrusive bold, and a full set of small caps.

Translations that require other scripts are using different typefaces.

If you have specific recommendations for other typefaces we should consider, or specific complaints about the current typeface, please let me know.

It’s still too much text and jargon for a new user.

Agreed.

There’s still not enough pictures with arrows, circles and highlights—even cropped screenshots of relevance could go in the right margin/column.

I agree with this, too. We’re looking at methods of annotating screenshots for the Maverick edition. We’re rewriting Quickshot and greatly expanding its capabilities.

Not nearly enough pictures break up the text.

This is due to a couple reasons: (1) We wanted to limit the number of screenshots in this first release because we were still writing the Quickshot program and taking good screenshots takes time. (2) We wanted to keep the size of the PDF manageable. We have some ideas for reducing the file size of the the PDF by further compressing the screenshot images, but we need to run some experiments to ensure we don’t degrade the quality too much. (Currently, nearly half the size of the PDF is due to the screenshots.)

Put the text next to the relevant pictures. I need to see what it is you’re talking about. Don’t give me a whole page of text about Gnome desktop then overleaf give me a picture of a blank one with no highlighting.

I concur. We’ll try to do better in future editions.

There’s not enough links to glossary entries. The glossary is too slim.

The glossary was something we added at the last minute. (This is primarily my fault, as it took me a while to get the code in place to support the glossary. Similarly, the index.) The glossary and index will both be expanded and improved upon in future editions.

The licence should be a link to a webpage, not a re-print of the whole text (most users don’t care, you just wasted a bunch of pages).

You’re right in that most people don’t care at all about the license. However, keep in mind that the final product is a printed book, not simply a PDF viewed on a computer screen. Not everyone has the Internet access required to view the license online. We want anyone using the book to know that they are allowed to freely make copies of the book.

‘Colophon’ !!!??? Seriously??? I know it may be correct, but now you’re just showing off…

Heh. Fair enough. The colophon has nothing to do with correctness. It was added at literally the last hour by me. We had to add another couple pages to make the page count come out to a multiple of four due to the printing process. If we didn’t have anything there, it would’ve been a blank page. So I figured we may as well put something on that page and I have a fondness for colophons. I like knowing how books are made, and I thought it would be a nice way to highlight the open source software, open fonts, and graphics that we used to create the manual. I don’t think the colophon is in the way of anything and no one’s forcing you to read it.

And I could go on. How long have you got…?

I’ve got plenty of time! Keep the criticism coming—it’s very helpful and I’ve made several notes about things we should improve in our future editions. Thanks again for such a thorough critique—I really appreciate it!