Book review: Planning and Structuring User Assistance

August 6, 2013



This was the second book I read from Marc Achtelig’s Technical Documentation Solutions Series. Like the first one I read (‘Designing‘), it was well-written in plain, simple language, and was laid out in such a way that I could dip in and out of it and use it as a reference book. While I read it from cover to cover for this review, I would expect that most readers would use it as a reference as each topic can stand alone.

Marc states that the intended audience for this series of books are:

  • full-time technical writers
  • developers, marketing professionals, and product managers who occasionally write some technical documentation
  • designers who create templates for user manuals and online help systems
  • multimedia experts who create screencasts, tutorials, and e-learning courses.

In my opinion, this Structuring book is mostly for technical writers or anyone else involved in writing product documentation (software or hardware).

The topics covered are:

  • General structuring principles
  • Choosing media
  • Planning documents
  • Planning document sections
  • Planning topics
  • Planning the order of sections and topics
  • Planning navigation.

As with the first book, in the author’s note in Chapter 1, Marc talks about the rules for designing templates and my first reaction was ‘Whose rules?’ Different organizations, industries, and countries can have different ‘rules’, so I was concerned that Marc was going to focus on a particular set of ‘rules’ that were familiar to him, but not necessarily apply to everyone else. However, he surprised me by his ability to make solid generic recommendations that crossed all sorts of boundaries and therefore that could apply to most situations.

In this book he starts straight in on what he calls the ‘universal principles’; specifically:

  • Don’t try to please everybody
  • Make it goal-centered (‘it’ being the document, topic, section etc.)
  • Layer information
  • Split complex information
  • Find the right amount of redundancy.

And further: ‘A user-friendly structure should reflect:

  • the tasks and goals of your primary user group
  • the information needs of your primary user group
  • the mental model of your primary user group’

I particularly liked the inclusion of ‘mental model’ in this list as I think it’s an aspect that often gets lost when we are defining who are users are.

And I LOVED this (p64-65):

What you shouldn’t include at all (in the preface):

  • Don’t congratulate users on choosing or buying your product. Most users don’t read manuals before using a product. They only read a manual when they have problems. Congratulating them in a situation like this may sound cynical and doesn’t add any information and value to your document. Phrases like this just stand in the way of the real information.
  • Don’t say that you’re pleased that users chose your product. Users don’t care about your feelings.

Note: It’s perfectly OK and important to build up a positive attitude toward your product. However, do so by providing value rather than words. Give users a reason to love your product and its documentation rather than telling them how wonderful both are.

Most of the notes I took as I was reading the first book also applied to this one, plus a few more specifically for this book:

  • Nice clear writing, with practical examples.
  • Excellent coverage of the basics and the do’s and don’ts. Good examples.
  • Excellent refresher for experienced practitioners; great advice for beginners.
  • Offers advice/rule and clear reasons for doing/not doing it.
  • All diagrams were clear and simple and got the message across successfully.
  • In this book he emphasizes the human touch required for indexing, and advises staying away from the automated indexes created by authoring tools; this is in direct contrast to what he said in the Designing book, and is a recommendation I agree with.
  • Unlike his Designing book, this one focuses more on online help.
  • Very comprehensive.

I only had a few negative comments about this book:

  • As with the first book, I read a PDF version of this book on an Android tablet (via Adobe Reader). There were some issues with odd artefacts in the PDF, e.g. single and double quote marks, en and em dashes all rendered as odd characters. This should have been checked/dealt with when the author verified the PDF output from their single-sourcing authoring tool as there were far too many for it to be an odd occurrence. UPDATE: The author sent me a couple of revised versions with different Adobe settings and one of those worked very well, with no artefacts displayed at all. He assured me that he had embedded the fonts and checked the display. If nothing else, this has shown that the same software on different platforms and different devices may render the text differently.

Overall, this is an excellent guide to planning and structuring electronic and printed product documentation. It is suitable for beginners and experienced practitioners alike.

I’ll leave the final word to Marc:

When deadlines are close and budgets are tight, it’s better to provide medium quality information but excellent navigation than to provide excellent information but poor navigation.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: