Skip to main content

Keep documentation close to code

Where possible, keep documentation close to code so that readers and modifiers of the code are more likely to find it and keep it updates.

Examples​

  • Every repository must have a Readme.md at the root which communicates the project's capabilities, use cases and usage instructions.
  • A module within an application, should have markdown documentation that provides a summary of requirements and solution.

Confluence​

There are also scenarios when documentation in Confluence "further away" still makes sense, for example:

  1. Documentation for consumers that don't know have access to the repository.
  2. Documentation that it not project or repository specific.