...

Documentation tools best practices

General

• Every doc should have a clear audience and owner. Bonus points for establishing that in the header of the doc/space.

• Discoverability is key. Establish entry points and have links out to disconnected docs.

• Linking > Duplicating. When possible, establish a single source of truth. Link where necessary. It means you only have to keep one doc up to date and it is clearer when something is canonical.

• Archive more. More docs = more docs to maintain. If docs are out of date, we should be empowering folks to signal that they are out of date or just archive them.

GitHub / Read the Docs

Following OEP-19, documentation around code generally gets stored in GitHub (either to be read in GitHub or published to Read-the-Docs). This allows it to be searchable and live near the code it describes. It also describes different types of docs in GitHub and where to store them:

...