How much detail when writing technical documentation?

1. 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.

2. 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.

3. 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.

4. 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.

posted almost 8 years ago

CC BY-SA 4.0

aparente001‭

285 reputation 16 31 41 4

The acid test is this: Will the reader behave differently if they know this? If not, leave it out. The aim of user documentation is to enable the user to act correctly. Any detail that does not contribute to correct action slows the reader down and may reduce their confidence.

posted almost 8 years ago

CC BY-SA 4.0

Mark Baker‭

4371 reputation 12 1104 744 58

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.

posted almost 8 years ago

CC BY-SA 4.0

Monica Cellio‭ staff

2514 reputation 51 268 361 110