- The structure of the documentation follows https://diataxis.fr/. When writing or editing an article, read the relevant guidance from the Diataxis Framework before: https://diataxis.fr/tutorials, https://diataxis.fr/how-to-guides/, https://diataxis.fr/explanation/, https://diataxis.fr/reference/. https://diataxis.fr/compass/ tells you where belongs what and how do they relate.
- Document only public APIs and user-facing behavior - exclude internals, framework abstractions, and implementation plumbing - Users need actionable documentation on what they can use, not confusing details about internal mechanics they can't control
- Explain before showing - place explanatory text before code examples, not after - Users need context to understand code examples; "explain then show" improves comprehension and reduces confusion
- Create dedicated pages for substantial features - ensures discoverability and comprehensive coverage vs. fragmented mentions - Prevents users from missing features when they approach from different contexts (CLI vs. API) and allows features to be documented holistically rather than buried in subsections.
- Explicitly mark parameters/features as 'optional' in docs, even when types show it - reduces cognitive load for readers - Users shouldn't need to parse type signatures to understand optionality; explicit labels make documentation scannable and accessible to all skill levels
- Remove documentation sections explaining standard behavior that "just works" - keeps docs focused on actionable, non-obvious information - Users don't need explanations of things that work automatically; documentation should focus on configuration requirements, edge cases, and non-obvious behaviors that affect usage decisions
- Strip boilerplate from docs examples - show only the feature being demonstrated - Reduces cognitive load and helps readers focus on the specific API or pattern being taught without distraction from scaffolding code.
- Link to existing docs/API refs instead of re-explaining concepts - reduces duplication and keeps info in sync - Prevents documentation drift and outdated explanations by maintaining a single source of truth for each concept
- Link to canonical docs rather than duplicating content - prevents drift and maintenance burden - Consolidating documentation into existing files with cross-references keeps information consistent and reduces the effort needed to update multiple locations when changes occur.
- Avoid
# ruff: noqaor# type: ignorein doc examples - ensures examples stay correct and runnable - Skip directives hide bugs and type errors in documentation code that users will copy, leading to broken examples in the wild - Code file examples should have a title that shows the file name.
- Important lines should be highlighted or annotated with a comment.