Developing Quality Technical Information: A Handbook for Writers and Editors, Third Edition Book Review

As an enterprise and software architect the one thing I hate most about my job is documentation, yet the importance of doing documentation on sizable projects is what I find myself preaching about the most. One reason I understand the importance of documentation is that I came from an electronic engineering background. As an electronic engineer 93% - 97% of my time was consumed doing proof of concepts and documentation. Almost all of that time was documentation. It was just my luck that my boss was an English grammar teacher before moving into engineering. My documents came back very bloody. He used a red pen to mark up my documents. It took me 2 years, and a whole lot of tongue biting, but I started getting papers through him without a red mark. I still remember the first one. I walked outside to where the smokers took their breaks and let out a screaming "YES, Finally!!!" I have been without my grammar teaching boss for over 18 years now, and I am pretty sure if he came across the book reviews I am writing now, he would be sending me bloodied up copies!!! I really needed this book!! Technical documentation is a hard skill set to learn, at least doing good technical documentation is. I have been on Template Zombie projects where teams considered documentation complete when they had filled in enough templates to overwhelm the customer to the point where they would not have time to review 1/10 of what was being written. One project I was on built a documentation generator so it was easier to duplicate documents and only change the title and a few pieces of content. The sad part of that project was they got paid for each document handed in. The criteria for getting paid for use cases were that they had to have something underneath every heading in the document. Documentation should not be something you check off of the project's task list, it should add value to the project or it should not be done. This book will definitely help you make valuable documentation. I have listed the chapters below to give you an idea of what the book covers. Part 1: Introduction Chapter 1. Technical information continues to evolve Chapter 2. Developing quality technical information   Part 2: Easy to use Chapter 3. Task orientation Chapter 4. Accuracy Chapter 5. Completeness Part 3: Easy to understand Chapter 6. Clarity Chapter 7. Concreteness Chapter 8. Style Part 4: Easy to find Chapter 9. Organization Chapter 10. Retrievability Chapter 11. Visual effectiveness Part 5: Putting it all together Chapter 12. Applying more than one quality characteristic Chapter 13. Reviewing, testing, and evaluating technical information Part 6: Appendixes Appendix A. Quality checklist Appendix B. Who checks which characteristics? Glossary Resources and references When I came into the Dot Com Boom I found some software engineering, but most of what I found was the wild west and cowboy coding running rampant. The industry has not changed much since then. We just gave names to the chaotic processes to justify our lack of discipline. I continued my engineering practices and quickly learned how to document software processes and architectures, but convincing others to do it was a different story. The only way I have been able to show it has value is do it myself. After the team sees I am willing to suffer the boredom of documentation they tend to step in and help. That wouldn't happen if we didn't make use of the documentation and they didn't see value in it. It has been years since I have had someone to officially review it. This book really helps keep the important things in mind, and since there is no one else to review it, I can use all the help I can get. Right now one of the things I do to catch issues in my documents is have them spoken back to me using the speech capabilities on my computers. This helps me catch sentence structure issues, and some typos. It doesn't catch using the wrong their/there, insure/ensure, except/accept, and many more like sounding words that I mess up. I use Sparx Enterprise Architect to document systems. Behind every diagram you find the information that explains them. If that information is not simple to understand, and easy to read, the diagram's value falls greatly. Throughout the process you need to write for several different audiences. Your stakeholders are interested in different aspects of the system. Creating a clear view of what each type of stakeholder wants to see is a painful process, but it always pays off. It makes me think about the solution from angles I normally wouldn't. Not only think about them, but diagram and describe them in a way that the solution's diagrams and associated documents can stand on their own. It makes me justify and clarify all the decisions made about the system, before it is in production! Doing documentation is like coding. You start with a shell of what you are building, and you add the details to the different topics with each iteration of your development cycle. Your goal- to make simple, complete, accurate, logical, easy to understand documents. That is exactly what this book will guide you to do. There are tons of examples showing the original text, diagram, or screen shot of a design, and then the revised version. There are two really cool appendices and a nice glossary. The first appendix is a huge checklist for quality characteristic. The second appendix is a big chart showing which roles should be reviewing the different aspects of the document. Over all I found every chapter of this book valuable. As time goes on, the hardest part for me is keeping it all in mind. For that reason, this book will be staying by my side just like each of my current most useful programming books. If you do any documenting of software systems, this is a must read. Every software architect, enterprise architect, CIO, developer, tester, and project manager working on a software project, should have this book in his or her hands. You own to your stakeholders and yourself.

Developing Quality Technical Information: A Handbook for Writers and Editors (3rd Edition)

Developing Quality Technical Information: A Handbook for Writers and Editors (3rd Edition)