Developing Quality Technical Information
Developing Quality Technical Information

Authors: Michelle Carey, Moira McFadden Lanyi, Deidre Longo, Eric Radinski, Shannon Rouiller, Elizabeth Wilde
Publisher: IBM Press
Pages: 624
Audience: Those who produce technical documentation
ISBN-13: 9780133118971
Print: 0133118975
Kindle: B00L7ZKJ26
Rating: 3.5
Reviewer: Kay Ewbank

 

 This book gives clear and well written advice on how to write technical documentation, though you may think the advice given is obvious.  

 

This is the third edition of a book that first appeared back in the 90s, and is still going strong. The latest edition has been updated again to reflect the increasing importance of online documentation as opposed to printed manuals and texts.  

Banner

 The book opens with a brief section introducing the role of the technical writer and how it has evolved. The authors then get straight into ways to produce good technical documents, starting with the fact documentation should be easy to use. You might think this is obvious, but just think of all the manuals and documents you’ve read that are incomprehensible. The chapters in this part of the book discuss task orientation (write for the intended audience, focus on users’ goals); accuracy (research and verify your information, be consistent); and completeness (cover all subjects that support users’ goals, and only those subjects). Again, all fairly obvious but often ignored.

Part III is titled 'Easy to understand’, and has chapters on clarity (write coherently and avoid ambiguity); concreteness (relate examples to knowledge or experiences the users already have); and style (use active and passive voice appropriately and be consistent over grammar).   

 

devqualtinfo

 

The next part of the book considers how to make information easy to find, with chapters on organization (put information where users expect it); retrievability (optimize for searching and browsing); and visual effectiveness (use meaningful graphics).

The book ends with a section on putting it all together that has a useful chapter on reviewing and testing technical information.

I wasn’t at all sure what rating to give this book. It’s well written, easy to read, and makes some useful points, but I kept thinking that surely this is all just obvious stuff. Then again, a brief glance at the manuals or online documentation for just about any software or hardware product you care to mention shows that this obviously isn’t obvious stuff.

If you have to maintain documentation, it’s worth reading, but be prepared to think it’s all fairly obvious. 

Banner
 


Oracle Exadata Expert's Handbook

Author: Tariq Farooq, Charles Kim, Nitin Vengurlekar, Sridhar Avantsa, Guy Harrison, Syed Jaffar Hussain 
Pages: 544
ISBN: 978-0321992604
Print: 0321992601
Kindle: B00ZY1K0PK
Audience: Oracle Exadata DBAs and DMAs
Rating: 4.5
Reviewer: Kay Ewbank

If you need to understand and use the Oracle Exada [ ... ]



Professional Microsoft SQL Server 2014 Administration

Author: Adam Jorgensen et al
Publisher: Wrox
Pages: 936
ISBN: 978-1118859131
Audience: DBAs and SQL Developers
Rating: 4.5
Reviewer: Ian Stirk

This book aims to give a professional understanding of a very broad range of administration topics, how does it fare?


More Reviews

 

Last Updated ( Wednesday, 11 February 2015 )
 
 

   
Banner
RSS feed of book reviews only
I Programmer Book Reviews
RSS feed of all content
I Programmer Book Reviews
Copyright © 2017 i-programmer.info. All Rights Reserved.
Joomla! is Free Software released under the GNU/GPL License.