Notes Old site

Forms of documentation

Documentation may take many different forms:

  • A separate document is often used for long, formal specifications that are themselves subject to review and sign-off. Records of changes and versions may also be kept in a separate document or database. The potential disadvantage of a separate document is that it may be difficult to maintain consistency between the documentation and the spreadsheet.
  • Implicit documentation is widely used. The names of worksheets, ranges and cells, and modules and variables in VBA code come into this category. Formatting may also provide documentation, for example if colours are used consistently to indicate which cells are inputs, or to indicate potential errors.
  • Documentation within the code is perhaps the most common form. It is particularly easy to use in spreadsheets (compared to other types of software) as it often simply takes the form of text in cells. It is well suited to instructions and some types of explanation, as it can be placed close to the cells to which it refers.
  • Documentation as a separate block in code, for example as a separate worksheet, can be very useful, especially for keeping records.
  • Documentation in the user interface overlaps with documentation within the code for spreadsheets, but is clearly distinct in more conventional software. It includes text in user forms, text boxes and other images.

The most appropriate documentation method depends on the type of documentation and the user for which it is intended, as well as the culture in which it will be used. If your team commonly uses separate documents or centralized systems for specific types of documentation, then you should conform to the common practice.


The following external links are relevant: