Mr. Procedure Discusses Procedures–Documenting Software (Part 1)

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 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!

About Tim James "Mr. Procedure"

A communicator; all-purpose capability in writing, designing and presenting training for all facets of organizational function. While my focus has been manufacturing, my training/development experience includes supervisory and lead person development, audit processes, continuous improvement and Lean, and Quality Management System implementation.
This entry was posted in Instructional Communication, Procedures, Software documentation, Training, Uncategorized and tagged , , , , , , . Bookmark the permalink.

3 Responses to Mr. Procedure Discusses Procedures–Documenting Software (Part 1)

  1. This is a tough one. I think you are on the right track as far as what you have described you are doing (in your 5th paragraph). This type of situation might be one of those where you must decide where you need to leave off and let training step in (if there is a training dept.). Once you cover the more basic functions, your end-use will actually need to learn to use the software to an extent that the user manual no longer covers. Think about companies such as Microsoft and such. Think about Windows and how far indepth they could go. They teach end-users merely the basics and the rest is left up to training programs. Hope this makes sense and helps a bit.

    • Hi Mr. Guru! Thanks for commenting. You allude to an excellent point that I thought about and was not sure how to address. But when you discuss software and documenting of same, there are so many different types and varieties of software. Something like Windows, Word or Excel have so many features and have to service so many different customers, that a manual could easily be in excess of 10,000 pages it would seem. Other software (accounting or tax software, e.g.) is much more focused in its intent. As far as determining where I would leave off and let training take over, I have been fortunate (!) that I have always been both the tech writer and trainer. Certainly that informs my approach. My tendency is to treat the things I want to do with the software as the primary task and understanding the software itself as the supportintg skill. This topic is still very new to me but the fact so many tech writers are now immersed in documenting software, I want to understand to the best of my ability what works (and maybe what doesn’t). Thank you for your valuable contribution. Others?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s