Welcome!

Related Topics: Containers Expo Blog, Microservices Expo, Microsoft Cloud, IoT User Interface

Containers Expo Blog: Book Review

Developing Quality Technical Information: Third Edition

A Handbook for Writers and Editors

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)

More Stories By Tad Anderson

Tad Anderson has been doing Software Architecture for 18 years and Enterprise Architecture for the past few.

Latest Stories
The cloud competition for database hosts is fierce. How do you evaluate a cloud provider for your database platform? In his session at 18th Cloud Expo, Chris Presley, a Solutions Architect at Pythian, gave users a checklist of considerations when choosing a provider. Chris Presley is a Solutions Architect at Pythian. He loves order – making him a premier Microsoft SQL Server expert. Not only has he programmed and administered SQL Server, but he has also shared his expertise and passion with b...
"IoT is going to be a huge industry with a lot of value for end users, for industries, for consumers, for manufacturers. How can we use cloud to effectively manage IoT applications," stated Ian Khan, Innovation & Marketing Manager at Solgeniakhela, in this SYS-CON.tv interview at @ThingsExpo, held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA.
As data explodes in quantity, importance and from new sources, the need for managing and protecting data residing across physical, virtual, and cloud environments grow with it. Managing data includes protecting it, indexing and classifying it for true, long-term management, compliance and E-Discovery. Commvault can ensure this with a single pane of glass solution – whether in a private cloud, a Service Provider delivered public cloud or a hybrid cloud environment – across the heterogeneous enter...
Without a clear strategy for cost control and an architecture designed with cloud services in mind, costs and operational performance can quickly get out of control. To avoid multiple architectural redesigns requires extensive thought and planning. Boundary (now part of BMC) launched a new public-facing multi-tenant high resolution monitoring service on Amazon AWS two years ago, facing challenges and learning best practices in the early days of the new service. In his session at 19th Cloud Exp...
The cloud promises new levels of agility and cost-savings for Big Data, data warehousing and analytics. But it’s challenging to understand all the options – from IaaS and PaaS to newer services like HaaS (Hadoop as a Service) and BDaaS (Big Data as a Service). In her session at @BigDataExpo at @ThingsExpo, Hannah Smalltree, a director at Cazena, provided an educational overview of emerging “as-a-service” options for Big Data in the cloud. This is critical background for IT and data professionals...
Today we can collect lots and lots of performance data. We build beautiful dashboards and even have fancy query languages to access and transform the data. Still performance data is a secret language only a couple of people understand. The more business becomes digital the more stakeholders are interested in this data including how it relates to business. Some of these people have never used a monitoring tool before. They have a question on their mind like “How is my application doing” but no id...
@GonzalezCarmen has been ranked the Number One Influencer and @ThingsExpo has been named the Number One Brand in the “M2M 2016: Top 100 Influencers and Brands” by Onalytica. Onalytica analyzed tweets over the last 6 months mentioning the keywords M2M OR “Machine to Machine.” They then identified the top 100 most influential brands and individuals leading the discussion on Twitter.
What happens when the different parts of a vehicle become smarter than the vehicle itself? As we move toward the era of smart everything, hundreds of entities in a vehicle that communicate with each other, the vehicle and external systems create a need for identity orchestration so that all entities work as a conglomerate. Much like an orchestra without a conductor, without the ability to secure, control, and connect the link between a vehicle’s head unit, devices, and systems and to manage the ...
More and more brands have jumped on the IoT bandwagon. We have an excess of wearables – activity trackers, smartwatches, smart glasses and sneakers, and more that track seemingly endless datapoints. However, most consumers have no idea what “IoT” means. Creating more wearables that track data shouldn't be the aim of brands; delivering meaningful, tangible relevance to their users should be. We're in a period in which the IoT pendulum is still swinging. Initially, it swung toward "smart for smar...
"We are an all-flash array storage provider but our focus has been on VM-aware storage specifically for virtualized applications," stated Dhiraj Sehgal of Tintri in this SYS-CON.tv interview at 19th Cloud Expo, held November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA.
In an era of historic innovation fueled by unprecedented access to data and technology, the low cost and risk of entering new markets has leveled the playing field for business. Today, any ambitious innovator can easily introduce a new application or product that can reinvent business models and transform the client experience. In their Day 2 Keynote at 19th Cloud Expo, Mercer Rowe, IBM Vice President of Strategic Alliances, and Raejeanne Skillern, Intel Vice President of Data Center Group and G...
"We are a modern development application platform and we have a suite of products that allow you to application release automation, we do version control, and we do application life cycle management," explained Flint Brenton, CEO of CollabNet, in this SYS-CON.tv interview at DevOps at 19th Cloud Expo, held November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA.
Information technology is an industry that has always experienced change, and the dramatic change sweeping across the industry today could not be truthfully described as the first time we've seen such widespread change impacting customer investments. However, the rate of the change, and the potential outcomes from today's digital transformation has the distinct potential to separate the industry into two camps: Organizations that see the change coming, embrace it, and successful leverage it; and...
In IT, we sometimes coin terms for things before we know exactly what they are and how they’ll be used. The resulting terms may capture a common set of aspirations and goals – as “cloud” did broadly for on-demand, self-service, and flexible computing. But such a term can also lump together diverse and even competing practices, technologies, and priorities to the point where important distinctions are glossed over and lost.
All clouds are not equal. To succeed in a DevOps context, organizations should plan to develop/deploy apps across a choice of on-premise and public clouds simultaneously depending on the business needs. This is where the concept of the Lean Cloud comes in - resting on the idea that you often need to relocate your app modules over their life cycles for both innovation and operational efficiency in the cloud. In his session at @DevOpsSummit at19th Cloud Expo, Valentin (Val) Bercovici, CTO of Soli...