Skip to main content

Docs as Code

Practices

  • Docs are written in plain text formats such as Markdown or reStructured Text.
  • Docs are stored as flat files, not database entries.
  • Docs are authored in a code editor of the writer's choice, not a monolithic authoring application.
  • Docs are kept under version control.
  • Doc versions are organized in parallel to product versions.
  • Docs are built and deployed from source in an automated process that mirrors product deployment.
  • Docs are automatically tested for internal consistency and compliance to style guides.
  • Whenever reasonable, writers use the same tools and processes as developers.
  • Writers are integrated into the development team.

Benefits

  • Writers have more control over their authoring environment.
  • Less friction in the authoring process.
  • Elimination of inconsistencies between docs and product.
  • Less need for human proofreading.
  • Coordinated releases of docs with product.
  • Developers are more likely to contribute to docs.
  • Writers and developers have more awareness of and respect for each others' work.
  • Authoring and deployment tools are mostly free; hosting requires less overhead.

Comments

Comments powered by Disqus