The topic of documenting software came up in one request for my Writing Operating Procedures book. This is an important topic to all technical writers and would-be technical writers, because writing in support of software applications is a significant and growing piece of the technical writing pie. I personally have not written documentation for software spefically, but I have documented the software aspects of machines as part of operating procedures. Frankly, I find it the most tedious part of the procedure writing I have done.

In my current role, I write manuals for capital equipment that is entirely driven by software, so I have had to wrestle with exactly how best to document the software in a manner that benefits the equipment’s end user the most. So I will provide the insights I have gained, while at the same time asking readers to give their feedback, particularly those who have done a significant amount of software documenting.

I have approached software in the same manner I approach operating procedure development for a piece of equipment. If the software is part of the equipment, then I treat it as part of the equipment controls (see Section 7 of Writing Operating Procedures; if you need a copy in order to see it, write me at mrprocedure@gmail.com). That seems to work well, until the software is so complex and so full of features that a typical user would learn or use only a small percentage.

But to the person writing about a software program, the software is the equipment. In essence, the screens of a software program would be the equivalent of major components of a process machine. My tendency would be to structure the software documentation in the same manner as I would a large piece of equipment. (Again, that is my mentality based on my background, so please don’t hesitate to set me straight.)

I begin by delineating what the software is (conceptually, structurally, what it is designed to do) and how the software is used (what specific activities would be performed using the software). So after a general overview of the software (using my “wading into progressively deeper water” method of layering information), I then discuss basic commands, then move into more specific discussions of commands and functions. Once I have established the nuts-and-bolts of operation (equivalent to describing features and controls), I would begin to discuss specific activities performed with (or using) the software.

From a training point of view, I would view mastery of the software as a skill, while I would view the specific repeated processes performed using the software as tasks. For example, I may use Microsoft Excel to maintain schedules, inventory reports and other types of information. For a person in the role, Microsoft Excel is a skill I either identify in a recruit or have someone learn. The specifics of each process (where information is gathered, who gets the output, etc.) are then described in an operating procedure that does not have to describe every keystroke in Excel.

This is a start to the discussion of documenting software. There are other issues I will discuss in future posts related to software. One concern: to what depth do I describe the functions of the software? In theory, every single function is documented in some way, but I feel I would drive people to 23rd floor windows if I actually described a software product in so linear a fashion. But I will take a stab at it in my next post. And please, enlighten me on the limitations of my thought process! I need to learn too!