techdocs icon indicating copy to clipboard operation
techdocs copied to clipboard

Suggested doc: Documentation home best practices

Open nate-double-u opened this issue 2 years ago • 0 comments

Where should documentation be housed in reference to a project's code repository?

  1. Documentation should be separate from the code, preferably in it's own website repository. Avoid duplication, source of truth for documentation is the website
  2. Documentation should be stored in the primary code repo, closest to the system being documented. Monorepo-style tools/organization can be used to generate a website from there
  3. Other(?)

I think that the TechDocs team tends towards option a., but each project is unique and other options are valid. I think we should put together a document that outlines our arguments for and against different strategies so we can refer to it as we're helping projects make decisions around how to setup their docs repositories.

nate-double-u avatar Dec 07 '21 18:12 nate-double-u