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.
- Falsifiable documentation is testable
- Copy and pasted examples should compile with the expected result
- See Microsoft’s Azure site for an example of excellent docs
- 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.