Reminiscences: software documentation

I feel fortunate that I can't identify first-hand with Tina, the long-suffering tech writer in Dilbert. My desire to provide user and administrator manuals for software applications stem back to even before I entered the professional workforce. The motivations, however, didn't stem from any false hopes that there would be any significant audience for said work.

As an undergraduate I eventually ended up majoring in a combination of Technical Communication and what they call Brain & Cognitive Science, which involved neuroscience, psychology and linguistics. I also worked at the university libraries, where I spent one summer cataloguing musical recordings by the various ensembles over several decades (mainly on vinyl). It was the following year, that their adoption of a system from OCLC (I believe it was Connexion, but I could be mistaken) led to an opportunity to create an administrators' concise guide.

When later I arrived at a documentation role, I found that structuring the manuals made the most sense if they included the following sections:

• Overview (or purposes of the software application)
• Instructions that were based on use cases, ordered from most to least common
• Troubleshooting
• FAQ, including known issues and limitations
• Index

In creating content to populate these chapters, I'd also generated black box testing use cases that covered installation, configuration, updating (or as Indian English speakers would likely say, updation), uninstallation for administrators, as well as the individual features the application offered to end users.

The discipline involved in condensed but clear writing was cathartic for me, but it's now been a very long time since I have had to practice it. Perhaps those reading my blog would prefer that I do so...