HomePractices Writing a Software Technical Reference Manual (part 1)
Writing a Software Technical Reference Manual (part 1)
For most developers, writing code is the easy part - it'sexplaining it to a customer that's the tough bit. In case you need tocreate a technical manual explaining how your software works, take alook at our handy two-part cheat sheet, which should help make theprocess a little less intimidating.
If you've been following this column regularly, you already know thebasics of writing a user manual. It's pretty simple - put yourself inthe mind of the user, and try to answer his or her most frequently askedquestions in a concise and effective manner.
This article, however, deals with a different beast, one that is not soeasy to tame - the Software Technical Reference Manual (STRM). Writtenespecially for developers, programmers, software architects and otherassorted geeks, it's usually filled with technical gobbledygook andcomplex diagrams illustrating the guts of a software application. It'scomplicated, intimidating and usually fairly stressful to write...andthey'd usually like it yesterday, please.
Over the next few pages, I'm going to offer you a few tips andtechniques, culled from my own experiences, that might help in makingthe process of developing such a manual less painful. As you'll see,proper planning and the right attitude can play an important role here,enabling you to both get your arms around the technical details andcompile them into a usable, structured format that serves the needs ofyour customer.