- Books, Literature, and Writing»
- How to Write
The IBM Technical Writing Trilogy
IBM has been a leader in many fields of office and computer technology since it was founded more than 100 years ago. Its recent leadership activities have included cognitive computing, in which human-like perception and reasoning is programmed into computers.
To make IBM products more usable, high quality technical instructions must be written. So it's no surprise that IBM has emerged as a leader in technical documentation, with the recent publication of three books that cover different areas of IBM's technical writing process.
The contents of these books started out as internal IBM work processes, but they can be valuable tools for any technical writing team.
The IBM trilogy of technical writing books includes:
- A general outline for technical writing (Developing Quality Technical Information)
- A style guide to help make the writing and formatting of material clear and consistent (IBM Style Guide)
- Guidelines for using the DITA (Darwin Information Typing Architecture) authoring process, which has been adopted by IBM and many other companies (DITA Best Practices)
Developing Quality Technical Documentation: A Handbook for Writers and Editors (Third Edition) (2014)
By Michelle Carey, Moira McFadden Lanyi, Deirdre Longo, Eric Radzinski, Shannon Rouiller, and Elizabeth Wilde
This book gives the reader an organized approach to writing high quality documentation, with the focus on computer software applications. The book succeeds at that goal by breaking down a writer's work into three basic priorities:
- How easy is the documentation to use? Users are trying to get a task done. The less time that they have to spend with documentation, the more quickly they can finish that task. The technical instructions must focusing on the user's goals and give them accurate and complete information.
- How easy is the documentation to understand? This priority applies good writing standards to the content decisions of the first priority. The IBM Style Guide helps with this priority.
- How easy is the documentation to find? Documentation has no value if the user can't get to it, so the writer must make information as easy as possible to find within a book, help system, computer interface, or topic.
To support these priorities, the book includes detailed checklists that can be used as writing evaluation tools by writers, editors, and non-writer reviewers from development, quality assurance, and other areas. Also helpful are a detailed glossary and a section on resources and references.
As I read this book, I did have two concerns.
The book recommends that writers put as much information as possible in the user interface through field labels, pop-up help, and other methods. The authors often use the relatively new phrases "embedded assistance" and "progressive disclosure."
However, many writers might not be able to create user interface help, because of time, technical, or skill limitations. Also, many users might prefer offline documentation, so that they can read documentation before they start a software application or print out a task before they perform that task.
Another concern is the length of the book, which has more than 500 pages.
From my technical writing experience, writing teams can get caught up in long debates about the correct way to do something. These debates can easily lose sight of a writing group's main goal on a product development team—make a product easier to use, which in turn helps with customer satisfaction, which in turn helps with customer retention.
The thorough detail of this book could have the ironic effect of fueling such debates. Readers should combine the lessons of this book with usability testing and other research to get their work done both usefully and efficiently.
The IBM Style Guide: Conventions for Writers and Editors (2012)
By Francis DeRespinis, Peter Hayward, Jana Jenkins, Amy Laird, Leslie McDonald, and Eric Radzinski
This book helps with two challenges of technical writing that can create tension and waste time within a writing group:
- Deciding how to write or format something
- Justifying those decisions to editors, supervisors and other writers
This book is a valuable reference tool with many lists and tables that can help minimize these challenges. But it's also worth a complete read-through because of how it builds on the reader's existing knowledge of the English language to teach them how to be good technical writers.
The first few chapters re-enforce English class lessons in a technical writing context. These chapters cover language, grammar, and punctuation. Next are chapters that apply these basic writing rules to the bigger details of technical writing, like formatting, organization, and structure. From there, the topics get more specific, covering references, numbers, measurements, and computer interfaces.
Much of the reference value of the book is in appendices on marketing content, highlighting, and word usage. My personal copy of the book has bookmarks for capitalization, highlighting, commands, user interface guidelines, and word usage.
I should note that the book is most valuable for writers who are working with the DITA (Darwin Information Typing Architecture) method of authoring. This book complements the DITA Best Practices book that is part of the IBM technical writing library.
But this DITA-related material can still benefit non-DITA users with guidelines on:
- Topic organization (task, concept, reference)
- Highlighting, which DITA automates but which can always be done manually with non-DITA tools
DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA (2012)
By Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt
Many writing groups are now using authoring tools that use the DITA (Darwin Information Typing Architecture) method of authoring. The DITA standard uses XML (extensible markup language) to do the following:
- Automate the formatting of documentation
- Categorize documentation into three basic topic types (task, concept, reference), as well as specialties like troubleshooting topics
- Automate links in electronic documentation
This book covers those basic parts of DITA authoring, along with other features that take advantage of the XML element tagging of DITA:
If a writing group is getting started with DITA, this book covers DITA's usage of features that are familiar in other authoring tools like Microsoft Word and Adobe Framemaker:
- Topic-based writing, including topic re-use
- Conditional formatting
And if a writing group is considering or planning a move to DITA, this book has technical and management guidelines for converting existing documentation to DITA documentation.
© 2016 Bob Smith