-----
:permalink: best-practices-tech-writers-editors-review 
:title: "Book Review: Best Practices for Technical Writers and Editors"
:subtitle: Simply all the books your Documentation Team needs
:type: article
:intro: |
  I've been working in Technical Communications for nearly seven years now, first and foremost Technical Writer and more recently as Documentation Manager. In other words, my work revolves around manuals and online helps, authoring tools and guidelines, documentation standards and… you get the picture. 

  And yet, although I write articles and develop documentation tools in my free time as well, I rarely write about my job on this site. But when I was offered the opportunity to read and review Best Practices for Technical Writers and Editors, I just couldn't resist.
:tags:
- books
- review
- techcomm
:date: 2013-04-21 05:43:45.000000000 +01:00
-----

I've been working in Technical Communications for nearly seven years now, first and foremost Technical Writer and more recently as Documentation Manager. In other words, my work revolves around manuals and online helps, authoring tools and guidelines, documentation standards and… you get the picture. 

And yet, although I write articles and develop [documentation tools](/gliph/) in my free time as well, I rarely write about my job on this site. But when I was offered the opportunity to read and review [Best Practices for Technical Writers and Editors](http://www.informit.com/store/best-practices-for-technical-writers-and-editors-video-9780132929660), I just couldn't resist.


### Contents

*Best Practices for Technical Writers and Editors* is a bundle comprised of three must-read ebooks, specifically aimed at Technical Communications professionals:

* [IBM Style Guide, The: Conventions for Writers and Editors](http://www.informit.com/store/ibm-style-guide-conventions-for-writers-and-editors-9780132101301)
* [Developing Quality Technical Information: A Handbook for Writers and Editors, 2nd Edition](http://www.informit.com/store/developing-quality-technical-information-a-handbook-9780131477490)
* [DITA Best Practices, Video Enhanced Edition: A Roadmap for Writing, Editing, and Architecting in DITA](http://www.informit.com/store/dita-best-practices-video-enhanced-edition-a-roadmap-9780132929646)


#### IBM Style Guide

Every Documentation department needs a style guide. Even though different organization normally have different set of rules, conventions, guidelines and *house styles*, Documentation Managers often resort to a third-party guide, and the IBM's is definitely one of the most popular choices.

Within my company, the manager that came before me chose the Microsoft Style Guide: the main reason being that our division develops a set of products that run on Microsoft systems and follow Microsoft guidelines when it comes to designing interfaces. 

The Microsoft Style Guide is great, but if you chose the DITA route it may not be the best choice, because it simply doesn't mention it at all (at least the edition we have). If your organization adopted the [DITA](http://dita.xml.org/) standard, the IBM Style Guide is probably the best choice: IBM has practically created the standard, and this book includes frequent references to it (which are actual links to the other two books within this bundle most of the time, anyway).

Even though I wouldn't start revolution in my company by adopting the IBM Style Guide right now, I would still recommend it to anyone who needs a new style guide: it is very clear and concise, easy to consult, and it even includes some chapters on how to structure content and how to write for different audiences, topics which are covered more in-depth in *Developing Quality Technical Information*.


#### Developing Quality Technical Information

If you need a book to teach someone how to write technical documents, this is your Bible. I absolutely love this book (we have the first edition at work), and it is a must-read for all new and experienced writers.

*Developing Quality Technical Information* covers three main aspects of technical authoring, each made up of three distinct characteristics which constitute _quality_ technical information:

* Easy to use
  * Task orientation
  * Accuracy
  * Completeness
* Easy to understand
  * Clarity
  * Concreteness
  * Style
* Easy to find
  * Organization
  * Retrievability
  * Visual effectiveness
  
If you can master all of these, your documentation will be spotless. Each aspect is described in detail, with a plethora of examples. Every section of the book contains an one or more exerpts of fictituous documentation which goes through one or more rewrites to satisfy the requirements for a particular aspect. 

But by far the most useful feature of this book is the checklists at the end of every chapterm andI highly recommend printing them out and keeping them at end, at all times: Technical Writers can use them as reference while writing, whilr Editors and Managers can use them to evaluate/grade technical documents.


#### DITA Best Practices 

The primary goal of this book, as the title says, is to provide some *best practices* on writing using the DITA standard. However, do not fear: it does not assume any prior DITA knowledge and will walk you through the basic of topic-based authoring (and the threee main topic types: concept, task, and reference) then moving on to architecting content using DITAMAPS, content reuse, linking and conditional processing. 

This book will teach you all you need to know about DITA to write good documentation using the proper tags at the right time. Even if you (think that you) already know DITA, you'll definitely learn something new, like how to use the how to use the *toc*, *print*, and *printonly* elements as an alternative to conditional processing, or what to put in a *shortdesc* element.

It does not go too in-depth when it comes to tools – that would be beyond the scope of the book – although it does mention [Information Architecture Workbench](http://www14.software.ibm.com/webapp/download/preconfig.jsp?id=2009-09-02+13:57:13.308214R&S_TACT=&S_CMP=) (open source, Eclipse-based) for modeling content via ditamaps and [XMetal](http://xmetal.com/) is always featured in all the code sample screenshots.

### Format

This ebook is available in EPUB format, and is optimized for the iPad. This shouldn't stop you from downloading it if you own a Kindle, it just means that you'll have to spend a few minutes converting it to AKV using [Calibre](http://calibre-ebook.com/).

What you do loose when you convert the book bundle to another format is the videos that come with *DITA Best Practices* – which you wouldn't be able to play anyway. At that point, you may as well save a few bucks and get the [standard edition](http://www.informit.com/store/best-practices-for-technical-writers-and-editors-collection-9780132929653) instead, which doesn't include the videos.


### Conclusion

If you have just been hired as Documentation Manager and you need three essential books that will govern how your team writes ad structures documentation following one of the leading XML documentation standards, this bundle is definitely for you (and for your writers and editors).

Also, the fact that these three books are not merely glued together in one but contain handy cross references to each other is definitely a good thing – if you need *all three* books, that is. 

In my case, my company adopted the Microsoft Style Guide long ago, and our documentation has been written following *their* best practices and *their* stylistic conventions. Surely consulting another style guide doesn't hurt, but it may potentially generate some confusion especially with neophite writers. Furthermore, if your company does not plan to adopt DITA or uses another standard like [DocBook](http://www.docbook.org/), you won't really need *DITA Best Practices* either…

In short, this is a great bundle if you really need all the three books, but if only need one or two, it obviously makes more sense to just get what you need separately.