Apple's Software User Guide Diet
Apple's handheld devices are an example for miniaturization at work: with every new release, iPods have gotten a little smaller, and "incredibly thin" is the new "insanely great." Unfortunately, Apple has also miniaturized some of their software user guides.
Back in 2003, Apple introduced Keynote. The first release of this presentation software shipped in a "full-size" carton box, and inside that box you would find a well-written, 97-page user manual that covered every feature of the software. As a complement to that manual, the box also contained a four-page reference card with lots of full-color screenshots.
In 2005, Apple debuted the Pages word processor and combined it with Keynote to create the iWork office "suite." The software shipped in a slightly smaller box (whose graphic design sparked quite a few debates) and, consequently, the printed user documentation was printed on slightly smaller-size paper as well, but it still consisted of comprehensive user guides and reference cards, one each for Keynote 2 and Pages. It did not really make much of a difference that the reference cards did not feature screenshots anymore; what did make a difference, though, was that Apple decided to also reduce the font size for the printed manuals, making them a bit harder to read for people with vision problems.
Fast forward to iWork '08, and the box in which the software -- now also including the Numbers spreadsheet application -- is sold has been reduced to the size of roughly two stacked CD jewel boxes. Which, of course, is also reflected by the size of the user guide inside the box and, again, by further reducing the font size used inside that guide. Yes, the guide, because only one printed manual remains, and instead of extensively covering all features of all three applications, it presents introductions to each application's core features, filling less than 150 pages total. If you want to learn all the ins and outs of Keynote, Pages, and Numbers, you are referred to PDF files on the installer CD, the largest of which is comprised of some 300 pages.
Reducing the size of the carton box makes a lot of sense: it keeps storage and shipping costs low; reduces the use of natural resources for creating as well as shipping each box; and it makes the box look sleaker and more elegant. But this comes at the price of reduced usability of the enclosed documentation.
The usability of software documentation
The concept of usability applies to a software program's user documentation just as it applies to the program itself. Here are five suggestions for attributes by which the usability of a user guide may be judged. Please note that this is specifically about user guides, not online help systems, which differ in some respects.
Designed for the target audience
The user guide should reflect the complexity and depth of the application as well as the expertise levels of the average user. Consequently, a configuration guide for the Apache webserver will differ considerably from a manual for iPhoto in terms of tone-of-voice, usage of technical terms, number of screenshots, verbosity of instructions, etc.
That aspect of tone-of-voice is important, and even more so when writing beginner guides: no-one likes being talked down to, so it's essential that the author of the guide takes the user seriously, and that the focus for the user is in enjoying the discovery of new software features and gaining new skills in using those features, instead of having the feeling of not knowing anything about an application yet re-inforced by the way the user guide is formulated.
Comprehensive, yet concise
A user manual should be comprehensive by covering every feature in the application. A software developer or user guide author should not try to guess what the user may already know about the software. When keeping #1 in mind, a user guide could address different levels of expertise by special entry-level chapters that an advanced user could simply skip.
Comprehensive does not necessarily mean verbose, though, and it definitely does not mean that there is room for excessive marketing speak. A user guide is not an outright sales brochure.
Easy to navigate
A well-designed manual can serve both as a tutorial and a reference.
The best manuals I have seen present their material in such a clear structure that you can work through the book from beginning to end to familiarize yourself with the software as a whole, and yet easily find information on a specific feature if you need help while working with the application.
For printed manuals, a cleanly-structured table of contents and a comprehensive index make finding what you are looking for simple despite the lack of an active search function as found in online help systems or PDF viewers.
Optimized for display medium
The requirements for printed manuals differ quite a bit from on-screen guides distributed as PDFs, and the design of each should be optimized for the respective characteristics of the medium.
For printed manuals, a page size should be chosen that can be comfortably handled physically. The font-size must be big enough to read even for users with less than 20/20 vision, and screenshots and graphics need to show enough contrast for the same reason. Some white space next to the text is handy for scribbling down some notes while working through the manual. As a minor, yet crucial detail, a binding that allows the book to lie flat without having to break that binding first, is a major relief for anyone who is driven up the wall by a book that just won't lie flat.
For on-screen manuals, screen space is a precious resource. It should not be wasted by excessive white space on the user guide's pages even if that would look good in a printed copy. The user should be able to navigate and read the guide without too having to scroll individual pages when viewing the document at 100% zoom. At full zoom, the font size should allow for easy reading of all text -- including, e.g., tables and explanations in screenshots -- and the font should not become distorted or fuzzy too easily even when viewed at smaller zoom settings. Where appropriate, hyperlinks can help the user navigate the document.
Include printed manuals for screen-hogging software
As mentioned earlier, given the economical and ecological costs of printed manuals, it makes sense to reduce the amount of printed documentation that ships with software applications. However, there are some software programs for which resorting to an on-screen manual is just not a viable option.
When running an application that uses hardly any screen space -- think Calculator or iChat --, there is always ample room left for reading a PDF manual on-screen, so one can easily justify scrapping a printed guide. This is, however, not the case when working with an application of the "never enough screen space" type. If you have ever launched a higher-end media editor like Final Cut Pro, Logic, or ProTools, you will know that, no matter how big your computer's monitor, you will always use the application at full screen and still complain that you could always use another one of the nifty 30" Cinema Displays. For these kinds of applications, I consider an un-abridged printed manual a must-have feature.
Even when a printed manual is included, also throwing in an electronic version -- that is optimized for on-screen reading -- is a good idea, as it makes the complete reference materials available even when traveling with a laptop.
What about Apple's user guides, then?
So what about Apple's user guides: how do they fare with regards to these five criteria?
The iWork '08 manuals are too small in more ways than one: physical size, font size, screenshot resolution, and content. The full PDF manuals that ship on the CD are comprehensive, but they waste much screen real-estate with white space, require scrolling when viewed at the original size on a MacBook, and when zoomed-to-fit, the font is hard to read. And, as you can see in the screenshot, the iWork applications also are an edge case with regards to "screen-hogging."
Unfortunately, the same criticism even applies to at least one of Apple's Pro apps: Aperture. The printed manual that ships with Aperture is titled "Exploring Aperture." While this book provides a very well-designed, easy-to-follow, and fun introductory course to the software, it shares the same size issues found with the iWork '08 manual. Unlike iWork '08, though, Aperture is not an edge case when it comes to screen-hogging: software of this type should definitely ship with a full-size and complete printed manual.
Contrast this to the documentation that is included with the Logic Studio audio editing and recording suite: the two main manuals -- one on the application itself and another one on the instrument and effects plug-ins -- offer a luxurious 1,900+ pages' and almost 3 inches' worth of fine reference material.
I would hope that the powers that be at Apple will change their criterium for defining the required minimum size packaging for software products from the current "that installation CD must still fit in there" to "a useable printed manual should fit in the box." At least for complex, functionally "deep" applications like iWork, Aperture, etc., proper printed documentation is not a nice add-on, it's an essential part of the overall product. And with the in-house benchmark of the Logic Studio user guides, the required expertise for designing that proper printed documentation is definitely available.
Categories
Mac
Read More Entries by Jochen Wolters.
Become an O'Reilly Member
Visit the Digital Media Forums
Subscribe to the Digital Media Blog Feed
Subscribe to the Digital Media Newsletter
Thanks for bringing up a very important point, Owen, namely how to structure software documentation.
If you use the "user manual" moniker in the sense of a tutorial, I agree with you that an additional reference manual makes a lot of sense for some products, and it would be that reference manual that should cover _all_ features of the product, whereas the user manual may be restricted to just an introduction on how to use the most important ones.
Key in my opinion is, however, that every feature of the software must be covered somewhere in the documentation package that accompanies it -- regardless of whether it's a big, single manual or several (hopefully well-structured and -organized) ones and regardless, also, of whether it comes printed or in electronic form.
I remember trying to use a business solution software that sells for several thousand Dollars, and many of its help pages were completely blank except for the friendly reminder that "This page is yet to be written". When asking the maker's support guy about this, he said that I could call him anytime I had a question about how to use those as-yet-undocumented features. Thanks, but _no_, thanks!
I also agree with you that putting printed manuals in _every_ software package would be a huge waste of resources -- both ecological and economical. However, as mentioned in point 5 in the blog post's list above, there is a type of software that, in my opinion, needs to ship with extensive printed manuals, and that is software for which you can never have enough screen real estate. While this certainly includes high-end graphics/audio/video editing software, apps like iWork or Aperture are probably an edge case.
Having said that, I do find it extremely disappointing what Apple has done with iWork '09 in terms of documentation: the only remaining printed documentation is a four-page flyer with installation instructions. Selecting "User Guide" from the Help menu in any of the three applications, though, and you're taken to a website from which you can _download_ the manuals.
Admittedly, these are well written, well structured, and well designed, and they also include as a fourth volume an extensive, 350+ pages long reference guide -- there you go! ;) -- to iWork's formulas and functions. However, why these 40megs' worth of PDF files were not included on the installation DVD, so that selecting that Help menu item will open the respective file in Preview instead of taking the user to a website, is beyond me.
And finally: when you mention that a "user will already have several consecutive versions of the user manual", do you mean that he has been going through several upgrades of that application and, thus, has several versions' worth of manuals?
The most elegant, but also most expensive, solution to this that I have seen was a ring binder that contained the manual (for RagTime 3, way back in the early 90s...): every upgrade came with bunch of new manual pages that would be added to the ring binder or replace existing ones to keep the manual current. A simpler option, of course, are addenda that only cover modified and/or newly added features.
In my opinion, these have an added benefit: they highlight the changes between versions. A full, revised manual makes it much more tedious for a seasoned user to find these changes and additions, unless the manual includes a "new in this version" section.
"A user manual should be comprehensive by covering every feature in the application"
I disagree. A reference manual, probably in PDF or HTML format, could do this much better. If we are talking about traditional printed manuals, for popular software, then printing every feature for every copy sold is simply a waste of expensive resources.
For the rare user that may one day use all the features, the manual is not likely to be the first or most trusted point of reference anyway. The odds are that by the time the user learns everything about the software, that user will already have several consecutive versions of the user manual. An online/onscreen reference is much more sensible in my opinion.
Owen
Rahel
At least the pro manuals (for Logic Pro, for example) I find very well written and designed. And they're printed too!
As for "social documentation," I do like the idea and some articles in the forums on Apple's Support pages seem to come close to what you suggest. However, the problem I see here is quality control: if Apple wanted to adopt that approach, they would have to ensure that the resulting documentation is consistently written, more or less complete, and, most of all, correct. Continuously monitoring such a collaborative effort is probably at least as work-intensive as writing a comprehensive manual from scratch.
Apple's reputation for providing less-than-helpful user support material (documentation, help files, etc) is legendary. The gaps get filled by passionate users who set up sites to fill in the gaps, or simply post to their own sites a fix to whatever problems they happen to encounter, and trust that entering an error message number will route other users through Google to find the answer.
Given Apple's unique value position in the market, you'd think that they would make the leap to social documentation. In other words, create the initial documentation, based on how you think customers will use a product, then incorporate feedback about what works for customers in terms of how they actually use the product, and provide a way for passionate users to aggregate their tips and fixes, and incorporate that into an uber searchable online documentation help area. Now, that would be a wow.
Mark:
The approach you describe sounds somehow familiar...
I especially like the point you make about missing out on less-obvious or somehow hidden features of an application: if you truly want to get the most out of any app, you should at least know which features are available, even if you don't use them all afterwards. Reading through a coherent tutorial makes it all the much easier to learn about those features than sifting through the bite-sized chunks of information usually presented in online help systems.
And, yes, let's not underestimate the importance of being able to read a paper manual in, umh, certain locations.
People learn in different ways. I usually open up and goof around with the app for a little while, then skim the documentation, screw around with the app a little more, and by that time I am oriented to the app's windows, menus and tools.
I then sit down and read all the documentation, cover to cover. After that I get to work in the app and a few months later I read all the documentation a second time.
Your knowledge is just too spotty if you don't read it all, and 1,000-page manuals are a hassle to read on screen. You need to be able to take them to the toilet, on the train, etc.
A Kindle version would be O.K., but the color screen shots would be missed.
Thanks for your comment, Sebastian.
Sounds like there are two aspects to your first sentence, first, whether printed manuals are still important, and, second, whether printed manuals are still important.
As much as I like a well-structure and well-written online help system, built-in intros, and online video tutorials as useful additions to a stand-alone user manual, I don't think they can fully replace such a manual. At least not for applications that are very feature-rich and/or whose features are very complex.
Exploring and trial-and-error may still work for the more common features of the iWork applications which you mention, but for someone who's less experienced with using such software, finding what they need may take an unnecessarily long time, and they may not find out about all the options a certain functionality has to offer. And once you head into media software technology, a comprehensive manual simply is a must-have, when confronted with something like, say, Native Instruments' REAKTOR 5 soft-synth behemoth, to name just one example.
It that sense, I would definitely say that "classical" manuals are still at least as important as the other documentation options available for software today. But do they really have to be printed?
I agree with you that, if layouters would optimize PDFs for on-screen viewing, printed manuals could be "banned" from quite a few software packages, thus providing the ecological and economical advantages you point out. And it is also debatable whether a printed manual should be in the box per default even for highly complex software packages.
And yet, I at least expect makers of complicated, hard-to-learn software to provide such printed manuals. Put them in the box for high-priced products that don't sell that many copies anyway, and offer them at a reasonable premium for others. But in case a printed document is offered, it should not be a mere excuse for a manual -- too small format to handle, too small font to read, too small content to be really useful -- but take into consideration that usability applies to documents, too.
That approach could make for a viable compromise between costs, environmental considerations, and customer/user orientation, I guess.
Printed manuals are just not important anymore, although I do agree PDFs need to waste less screen estate in general, the best way to learn software like iWork is to just jump in and start using them. They're not difficult to learn how to use after a quick overview of the app preferences and menu bar, and apart from PDFs and the printed user guide they also offer online videos which I believe they provide a link for as soon as you start an iWork app for the first time after installation that can be found at http://www.apple.com/iwork/tutorials/ .
Apart from the guides and tutorials they also have the built in documentation in Help Viewer, a printed guide just seems like a waste of paper, ink, and space when they could cut down even further on shipping costs and just remove the printed guides in favor of video tutorials and the built in documentation.
Sebastian