...

Documentation tools best practices

General

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

  • The audience dictates location/access rights e.g. is the doc/space tied to a repo, team, theme, or functional group; is it public or private.

  • The owner is responsible for lifecycle management. This means setting location/access rights when setting up the doc, and transferring or archiving a doc/space when it is moved or completed.

• Single source of truth. Establish rules for what is “canonical”. When information should be accessible from multiple places, link rather than duplicating pages.

• Discoverability is key. We need clear rules on what goes where and fewer, established entry points which act as indexes to linked docs.

• 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.

...