: Re: How much detail when writing technical documentation? As a software developer, I often find myself writing my own technical documentation and user guides. How much detail should be put into

@Angie602

Vote Up Vote Down

If you're working in a group, check the level of detail of existing documentation, and ask for guidance from your group leader, or a co-worker who seems to know what's what.
Picture an imaginary reader. Write a description of this ideal reader -- why is s/he reading your documentation, and what does s/he hope to get out of it? For example, you need to have clear in your mind whether the reader wants to simply use your software, or whether s/he wants to be able to modify it.
Perhaps you could provide two levels of detail. Analogy 1: Newspaper articles start with the very short version of the story, and then tell the longer version. Analogy 2: Eurogames often come with a short quick-start sheet, which skips the motivation and lovely prose, and just gives you a quick rundown of the set-up (preparation for play) and a bulleted list of the mechanics. A longer booklet can provide the story behind the game, a slow introduction to the pieces, tiles, etc. that one manipulates, notes about strategy and variants, and fine points about rules, etc.
Imagine that an editor writes to you and asks what the purpose of your article is, and why you took the approach you took. Write back to this imaginary editor. You'll probably find that writing about what you're trying to accomplish with your writing will help bring the project into better focus.

(0)

Login to post a comment!