devops-guide/docs/documentation.md

Documentation

Make it easy to understand, run, and contribute to your project — for future you and for teammates.

Tools by Language

Language	Recommended	Alternatives
Python	mkdocs + Material	sphinx, pdoc
JavaScript/TS	VitePress	Docusaurus, JSDoc
Go	pkgsite, godoc	(built-in tooling is strong)
C++	Doxygen	sphinx, mkdocs

Python — MkDocs + Material

Fast setup, Markdown-based, deploys to GitHub Pages in one command.

uv add --dev mkdocs-material
mkdocs new .
mkdocs serve          # live preview at localhost:8000
mkdocs build          # generate static site
mkdocs gh-deploy      # push to GitHub Pages

mkdocs.yml:

site_name: My Project
theme:
  name: material
nav:
  - Home: index.md
  - API Reference: api.md

What to Document

Minimum viable docs for any project:

1. What it does — one paragraph
2. How to install — exact commands, no assumptions
3. How to run — quickstart example
4. How to develop — how to run tests, linting, CI locally

Tips

• Docs live in the repo — version them alongside the code
• A README is documentation; don't skip it even for internal projects
• Generate API docs from docstrings (pdoc, pkgsite) rather than writing them twice
• Often skipped, always regretted — write docs when the code is fresh