Search icon Looking for something?

Cooking Light or Going Gourmet: Hardware v. Software Documentation
2016, Q2 (February 22, 2016)
By Ted Avery, STC Carolina Chapter Member

Ted Avery
Ted Avery
After being laid off from Lenovo (formerly IBM) where I documented small computer accessories for many years, the need to update to a different brand of technical writing became evident. In interviews, when asked if I had experience with software documentation, I would say that I included information on device drivers. That’s close enough, right? However, in my current work at SAS, I have since discovered that documenting computer software is much more complicated. It’s like the difference between planning and preparing a Thanksgiving meal and microwaving and setting out the game-day snacks.

Cooking Times May Vary

You want those Swedish meatballs and chili cheese nachos made quickly because the game is about to start. Similarly, I had to develop my hardware document quickly because the development time for the small products was usually short, no more than six months. Prepping for Thanksgiving can take a long time; there is much to do to get ready for the day. The turkey alone requires careful planning and preparation. Similarly, it can also take a long time to document software. The development cycle can be as long as a year. Although there is more time to produce documentation for the software, the product is too complex to wait until the last moment to finish the job.

Sampling the Fare

When you’re cooking, you want to sample the food while you’re cooking it to see how it’s going to taste. To improve the documentation, I found that it is important to work with the product to understand how it works. I often had to go to the testers’ lab to get hands-on experience working with the hardware product. Now I can work with the software without leaving my office because I can simply download the application to my workstation.


Sometimes you need instructions with helpful diagrams whether you’re microwaving popcorn or basting turkey. Many times the set-up instructions for the hardware required artwork for guidance. In a similar yet slightly different manner, the software artwork is designed like a map to help the user navigate the user interface.

Small and Large Portions

Small dessert plates may be able to hold your game-day snacks, but you’re going to need large dinner plates to support your Thanksgiving meal. Because I was documenting products such as keyboards and mice which had limited functions, the user manuals tended to be smaller, around 40-60 pages. In contrast, it takes hundreds of pages to document all the complex functions that are available to the software user.

Setting the Table

You don’t care about style points when you put out your game-day snacks, but you want to make Martha Stewart proud of your holiday table. I had no input on the look of the hardware products because the design phase was complete by the time I began creating the documentation. Currently, I am able to provide input and suggestions for the user interface because I am able to develop the documentation before the software is finalized. End of article.

More articles like this...
Comments powered by Disqus.