Documentation
Documentation should be…
- Precursory (start documentation before implementation)
- Participatory (include all stakeholders to document in different forms)
Content should be…
- ARID (accept repetition in documentation)
- Skimmable (have good structures that allow quick overviews)
- Exemplary (include some examples)
- Consistent (language and formatting)
- Current (keep docs up to date)
Sources should be…
- Nearby (close to code)
- Unique (avoid parallel maintenance)
Publications should be…
- Discoverable (where might the user look for docs)
- Addressable (make sections and subsections addressable)
- Cumulative (necessary basics first and then building up)
- Complete (of the chosen characteristics)
- Beautiful (“Visual style should be intentional and aesthetically pleasing.“)
A documentation body should be…
- Comprehensive (answer all questions a user might have)