add knowledge

docs/documentation.md

@@ -0,0 +1,51 @@
+# 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