Documentation

Documentation is something that’s a part of the environment and context. As such, it’ s just as important, if not even more so, than the code itself. Like code, it is a precise Good Explanation; however, unlike code, it cannot be computationally verified the same way. Rather than being a downside, it offers an opportunity to express ideas in non-computational form which can ease understanding.

  • Treat documentation like code. Whenever possible make it falsifiable.
  • Documentation often ends up being written as an unstructured graph. Whenever possible, restructure it back into a tree.
    • Restructuring in this case means offering and presenting traversals of the information in tree forms.
    • New users require information in a linear format
    • Returning users want to remember a minimal path to get to certain documentation. Trees are easier to remember than graphs because they lack cycles and have a clear direction.

resources