Who is helped by what documentation?

There is no type of documentation that is always useless to any type of user, but in general some types are more useful than others. The following table summarizes the general utility of the different types of documentation to different users:

The table can form the basis of a useful checklist when reviewing the presence and adequacy of documentation.

Specify

A fairly abstract level of specification is useful to everybody: “This spreadsheet models the effect of inflation on sales” for example. Some users need rather more detail than that: a Changer or Developer needs full details of the theoretical model that should be used, so that they can implement it, and a Tester needs those details so that they can see whether it has been implemented. You can’t tell whether a spreadsheet is doing the right thing unless you know what the right thing is. Even a Viewer or Player may need to know the theory behind the spreadsheet so that they can interpret the results.

Record

A record of what was done is especially useful to an Auditor, but is also helpful to Changers and Developers, who may need to work out why things are going wrong. However, a record is rarely a good substitute for either explanation or instruction. Recording documentation may be a simple narrative of steps taken, or a more formal record of versions, changes made, reviewers, tests performed, and so on. Information about the sources of data or parameters may count as either recording or explaining documentation.

Explain

Explanations of how the spreadsheet is put together, or why specific design decisions were made are usually primarily intended for Changers and Developers, but are also useful to Auditors. Explanations of the sources of data or parameters may be useful for all users. A simple narrative of “what I did when building this spreadsheet” is rarely useful as an explanation, especially as any information it gives may be superseded later on in the narrative. Explanations of the significance of outputs are useful to all users, especially Viewers or Changers who may not have the skills necessary to infer what is going on from the formulae or code.

Instruct

Instructions may be directed at any type of user. They are especially important for Viewers and Players, who may not always be able to infer what should be done from the structure or code in the spreadsheet itself.