- Align with the Diátaxis framework: Tutorials, How‑to Guides, Reference, Explanation
- Improve clarity, consistency, and task‑orientation
- Raise quality to industry standards (Stripe, React, Kubernetes, MDN)
- Required:
title, summary
- Recommended:
prerequisites, learning_objectives, estimated_time, difficulty, tags, last_updated
- Use Title Case for H1/H2/H3
- Keep headings unique; avoid duplicates within a page
- Always specify language fences:
bash, sh, json, yaml, go, ts, tsx, md, sruja
- Prefer copy‑ready commands; avoid interactive prompts where possible
- Use standard callouts: Note, Tip, Warning
- Keep callouts short and action‑oriented
- Prefer descriptive link text (not raw URLs)
- Cross‑link to Reference and Examples when teaching a concept or task
- Include small screenshots or diagram previews for expected outcomes
- Use alt text that describes the intent and context
- Structure: Overview → Prerequisites → Steps → Outcome → Troubleshooting → Next Steps
- Include at least one end‑to‑end task with an expected output
- Task‑oriented and concise
- Structure: Purpose → Steps → Validation → References
- Precise, complete, and skimmable tables/lists
- Avoid narrative; link outward to tutorials for workflows
- Conceptual background, rationale, trade‑offs
- Link to reference for details and to tutorials for practice
- Markdown lint for headings, lists, links
- Link checking for external and internal links
- Optional accessibility lint (alt text, heading levels)
- Front matter present and complete
- Headings consistent and unique
- Code fences have language tags
- Cross‑links added to relevant Reference/Examples
- Outcome preview or screenshot included where appropriate