Book review: Designing Templates and Formatting Documents

August 5, 2013



This was the first book I read from Marc Achtelig’s Technical Documentation Solutions Series, and I look forward to reading others. Why? Because 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 Designing book is also for the person in a small company who has to set up templates for others to use; for example, an admin assistant. While the sections related to online help wouldn’t apply to them, those on page layout, etc. would.

The topics covered are:

  • Layout
  • Type area
  • Fonts /spacing
  • Screen layout
  • Page layout
  • Table design
  • Paragraph styles
  • Character styles

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.

The other thing that surprised me was Marc’s ability to talk generically about authoring tools, yet not mention a single tool. But in no way did that detract from the information he provided — in fact, it enhanced it as he didn’t get caught up in what Word could do versus FrameMaker, versus RoboHelp, versus Flare, versus Author-it, versus any other authoring tool you might want to name.

Here are the notes I took as I was reading 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 for beginners.
  • Offers advice/rule and clear reasons for doing/not doing it.
  • Lots of advice on setting up templates, without referring to ANY authoring tool — a remarkable achievement.
  • All diagrams were clear and simple and got the message across successfully.
  • While online help is dealt with, the book would be ideal for anyone setting up a document, not just technical communicators. Ideal also for those new to the profession.

I only had a few negative comments about this book:

  • While I found the advice to use keyboard shortcuts and meaningful names for paragraph and character styles useful, I found the style name examples he gave quite unconventional (in my experience) and against the author’s advice to use style names that were easy to interpret and remember.
  • I disagreed with his assertion that ‘most Help authoring tools create a well-designed index automatically’. This has NOT been my experience, and a competent author/indexer is needed for a useful index, otherwise it’s just a list of topics or words used, without any weight given to their importance or their contextual use.
  • I read a PDF version of this book on an Android tablet. 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. Perhaps he didn’t follow his own advice on font selection and embedding… 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 designing electronic and printed document templates, suitable for beginners and experienced practitioners alike.

One comment

  1. […] The official newsletter/blog of CyberText Consulting – technical communication specialists « Book review: Designing Templates and Formatting Documents […]

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

%d bloggers like this: