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)

See also

• https://www.writethedocs.org/guide/writing/docs-principles/