: 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

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)

Vote Up Vote Down

It depends on who your readers are and what they are trying to do with the information. Documentation about the same product could have very different levels/types of detail depending on whether you are writing:

Task-oriented end-user documentation, where the focus should be on how to use it, ideally with some examples. This type of documentation might cover only common cases, and people often read it linearly. Example: user-level documentation for an email client that tells you how to send, read, format, categorize, etc.
Reference user documentation, where the focus should be on covering all the cases, but still only in ways that affect how a user uses it. People usually jump into reference documentation to look up something specific and haven't necessarily read any of the rest of it. Example: documentation of all of the options and settings in that email client, or Unix man pages, or API documentation.
Installation, configuration, or integration specifications for system administrators, systems engineers, and similar people. These people are users too, but they are not end-users and they are more likely to be concerned with questions like: What demands does this product place on my network? How do I integrate this with my single-sign-on security? How do I get usage reports? Example: documentation for an email server in an enterprise environment.
Specifications of various sorts, where the audience is not users but other people who interact with your feature: other developers, testers, an enterprise customer's technical reviewers, product managers, and so on. Those different types of users have different needs when it comes to details. (I've grouped specifications into one bullet point here, but there are several types here.)
Deep-dive internal documentation for your coworkers so they could take over your code if you got hit by a bus.

There are more, but I hope these examples illustrate the situation.

When writing documentation, you need to ask yourself: "what do my readers need to know?" and, by extension, "what don't my readers need to know?". In order to do that, you need to have some idea of who your readers are and what they are trying to accomplish. Why are they reading your documentation?

Answer that, and you'll have a good idea of how much detail to supply. But if you still can't tell, ask for peer reviews early so you can recalibrate if you need to.

(0)

Vote Up Vote Down

It depends on who your target audience is and what the purpose is. If you are writing for uneducated users who just need to be able to use the product, keep details to the very minimum. Clear, logical steps that allow tasks to be completed is what's needed.

If, however, you want your user to understand how the product works so that they can use it more creatively, give more details.

Consider what some documentation does: What is needed for general consumption is the normal text, but there are specially labelled 'expert' sections -- read them if you need or want to. Alternatively, provide an introductory tutorial and then detailed technical information for people who want to do more.

(0)

Vote Up Vote Down

Just enough for your target audience to be able to use your product or duplicate your process.

If you are writing for professionals, you do not have to explain the difference between click and double-click. If you are writing for consumers, you might :-)

(0)