Revamp Documentation #71
Description
Our documentation needs to be modernize and reorganized in several places.
Here is how to keep track of the tasks involved, feedback welcome:
- Host docs under https://tim-janik.github.io/anklang/
- Use mkdocs-material for documentation builds.
- Add proper front-page (index.html)
- Integrate C++ API documentation, this needs C++ docs in markdown, possibilities: mkdoxy, moxygen
- Integrate JsDoc documentation about web components and JavaScript utilities
- Rewrite JsDoc Generator + JsDoc pges to work properly with mkdocs-material
- Display runtime help (via F1 key) at the UI, use the markdown-it renderer our UI supports already.
- Add PDF renderings (needs xelatex) to the online docs (TeX doesn't need to be a dep for all builds).
- Add design docs from the Wiki to the docs, like Architecture e.g. via a wiki submodule
- Restructure the documentation to start simple and provide progressively more details, e.g.:
- Tutorials
Lessons/exercise to learn from for beginners that cannot yet ask technical questions.
Writer decides actions & outcome, exercise turns learners into users. Must be bulletproof, 100% repeatable.
Does not explain, instead focuses on doing things without options/alternatives.
Basic concepts. - Guides / How-Tos
Problem oriented, takes through a series of steps. Provides answer to a meaningful technical question.
Some flexibility, covers alternatives/variations for slightly different problems users might have. Must be reliable.
Practical usability over completeness. Needs good sentence title: "Howto create a class-based view" - Reference
Technical description of the machinery. Code determines structure. Covers lifetimes, fields, interactions.
Provides information like an encyclopedia. Must be kept in sync with code. - Explanation / Discussion
Background explanations, historical contexts. Rationales for design decisions. Touches on approach alternatives.
- Tutorials
Related: What nobody tells you about documentation A Framework for Better Documentation
