Writing a Software Technical Reference Manual (part 1) (
Page 1 of 5 )
For most developers, writing code is the easy part - it's
explaining it to a customer that's the tough bit. In case you need to
create a technical manual explaining how your software works, take a
look at our handy two-part cheat sheet, which should help make the
process a little less intimidating.If you've been following this column regularly, you already know the
basics of writing a user manual. It's pretty simple - put yourself in
the mind of the user, and try to answer his or her most frequently asked
questions in a concise and effective manner.
This article, however, deals with a different beast, one that is not so
easy to tame - the Software Technical Reference Manual (STRM). Written
especially for developers, programmers, software architects and other
assorted geeks, it's usually filled with technical gobbledygook and
complex diagrams illustrating the guts of a software application. It's
complicated, intimidating and usually fairly stressful to write...and
they'd usually like it yesterday, please.
Over the next few pages, I'm going to offer you a few tips and
techniques, culled from my own experiences, that might help in making
the 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 and
compile them into a usable, structured format that serves the needs of
your customer.
Let's get going!
/ 11 
