Notes Old site

Who benefits from documentation

Just about everybody benefits from clear, accurate documentation. The benefits of out of date documentation written without a specific purpose in mind are less obvious, and indeed are often non-existent. To get the most out of documentation, the following should be true:

  • It should be written specifically as specification, record, explanation or instruction. That way it will be easy for the reader to understand.
  • It should be easily available to anybody who wants it; this often (but by no means always) means that it should be part of the spreadsheet that it applies to.
  • It should be kept up to date, otherwise it might mislead the reader.
  • When writing documentation, it is often helpful to bear in mind the specific type of user for whom you are writing.

It is not only the reader who benefits from documentation. The writer often gains a lot, too; if the writer is a developer, writing some of the documentation in advance can help to focus the mind and prevent false starts. Articulating your ideas can save you from many dead ends. The documentation process can often throw up bugs in the spreadsheet or ambiguities in the specification, especially if the writer is a user other than a developer of the spreadsheet.

Appropriate documentation will help people other than the developer have confidence in the results of a spreadsheet. They will be to able to tell what the spreadsheet is intended to do, how it does it, what data it uses, how to use it and interpret the results, and what tests and reviews have been performed.


The following external links are relevant: