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

```bash
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`:

```yaml
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