Ubuntu Manual Critique

I love that the Ubuntu Manual team has got the manual together, we now have something that didn't exist before. I know Mark appreciates the effort, I saw the name-check for Benjamin Humphrey in the UDS video!

As for the manual itself, now we have one to touch and feel, I've exchanged ideas with Benjamin only to find most of them are already in the plan for the next release... 

It may seem harsh, but I've had experience writing these things for software projects in the past. I don't know what debates and compromises were agreed along the way to this edition and I'm sure there's a bigger plan for the next one, but for what it's worth:

Who are we aiming this at - who is in our intended audience?
  • Windows-literate Linux converts?
  • Mac-literate Linux converts?
  • My elderly parents with bad eyesight (short and long-sighted), little patience and no memory?
  • My g/f (an Oxford graduate, hyper-intelligent luddite)?
  • New computer users? (Huston, we have a problem...)
I think you need to look again at intended audience, because right now not enough people will get past page 4.
  • 165 pages is still too intimidating a length for 'Getting Started'
  • 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.
  • Getting started should mean 'get me started in the next ten minutes. If I want to read a text-book to cure my insomnia I'll go to Waterstones..."
  • Look again at what is essential preparation and what is nice-to-know background.
    How many of the audience groups listed above give a flying #### about 'the philosophy of Ubuntu'?
    Yes, I know WE care...
  • Consider re-ordering the contents and lifting some to Appendices in back.
  • 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.
  • Consider task-oriented layout, what do I as user need to achieve
    (I know you think you have already).
  • Most people will use the PDF on-screen. Put it in landscape and 2- or 3-column. I'm scrolling too much.
  • That font just plain hurts my eyes.
  • It's still too much text and jargon for a new user
  • There's still not enough pictures with arrows, circles and highlights - even cropped screenshots of relevance could go in the right margin/column.
  • Not nearly enough pictures break up the text.
  • 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.
  • There's not enough links to glossary entries.
  • There's no internal links to related manual pages or sections
  • The glossary is too slim.
  • 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)
And finally...

'Colophon' !!!??? Seriously??? I know it may be correct, but now you're just showing off...  And I could go on. How long have you got...?  RC

Editorial Response
To which Benjamin already replied:
Hey Robin,
Good feedback. The cool thing is that we know most of that, it's not something new that we're not aware of. The next release is going to be rocking, mainly because we will have this: the Ubuntu Support and Learning Center.
Have a good read and you'll see that we plan on fixing most of your gripes as a by-product of having more formats.
Comeback, Good Buddy...
I saw the Learning Center and heard the podcast piece on persona's around which to base future manuals. Excellent ideas both.


  1. Hey, Robin.

    Thanks for an excellent critique! I'm one of the people helping out on the Ubuntu Manual Project. I've responded to a number of your points in a blog post.

  2. All good to hear Kevin and I know from the exchanges I had with Benjamin there's parallel development of the Learning Center on-line to go with this.

    You're right about getting the content first, then multi-platforming the print and on-line for different readers; that should take care of most of my gripes in one hit. I can see the evolution already.

    Looking forward to next editions. RC


Post a Comment

At least try to be nice, it won't kill you...