: 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

@Speyer920

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)

Login to post a comment!