4

As a software developer, I often find myself writing my own technical documentation and user guides. How much detail should be put into this documentation? When is it too much detail?

EDIT

I'm stuck on a user simply being able to follow a linear A->B process, vs. material that will teach the user how to use the software in a manner that will enable them to handle many errors or process deviations on their own.

  • Related question: writers.stackexchange.com/questions/26211/… – Neil Fein Jan 23 '17 at 17:22
  • 2
    So it seems your real issue is you do not know enough about you readers. You need to know what tasks they want to perform and what their backgrounds are. The only way to fix this is research. Your product manager or business analyst are a good place to start. They are supposed to know this stuff to do their jobs. – user16226 Jan 24 '17 at 16:27
  • The problem is that I'm my own company.... I do it all myself. – Jon Milliken Jan 24 '17 at 16:54
5

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.

  • In your first 2 examples, how do i get users to be (mostly) self-sufficient as opposed to only understanding a linear A->B process progression with no real understanding of how to handle errors or other deviations that may come from the "expected" linear process/use-case? – Jon Milliken Jan 24 '17 at 16:01
  • @JonMilliken that's a good question, and complicated (as I suspect you've discovered). It'd probably work better as a separate question about how to document a process where errors can come up along the way (so the process isn't strictly linear). – Monica Cellio Jan 24 '17 at 16:10
  • @JonMilliken oh, I saw your edit to the question after posting that. The broader question about details applies to things other than this case, and I think people answered that broader question here. – Monica Cellio Jan 24 '17 at 16:11
3

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.

2

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 :-)

  • Yes, but isn't the idea to provide a user with the understanding of how the product works more than a linear a->b process? What happens as soon as something unexpected (to the user) arises? For example they didn't do step 3 completely, and now an error is thrown on step 7? Do i detail the possible (unsuccessful) outcomes on step 7 and explain what to do to correct them? I want users to be (mostly) self-sufficient. – Jon Milliken Jan 24 '17 at 15:54
  • 1
    @JonMilliken If a possibility of an unwanted outcome on step 7 is considerably high, you might have to refer to that possible scenario in the troubleshooting section, and if you do, you do have to explain the way to remedy the situation. Your job is not to leave anything unexpected to the user, who by default doesn't know how to handle the situation. That would be the manual that actually helps. You may leave out the part "please, make sure the device is plugged in into the working wall outlet..." :-) – Lew Jan 24 '17 at 16:12
  • Troubleshooting section = good point. thanks. – Jon Milliken Jan 24 '17 at 16:18
1

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.

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

  • #3 is a very interesting point. I'm stuck on a user understanding a linear A->B progression vs. a user (mostly) understanding how the process works, and is able to handle the majority of unexpected cases. (IE Q: Why is this erroring for a blank field? A: Because another user didn't complete a different process yet) – Jon Milliken Jan 24 '17 at 16:06
  • 2
    My Toyota manual has a section at the back called "Troubleshooting." // If your users will understand some simplified pseudocode or flow charts, perhaps you could provide a more detailed appendix. // Question: when something happens that is unexpected, does the program provide an error code? If so, you could list the error codes in your documentation. – aparente001 Jan 24 '17 at 20:35

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.