Help us improve
Share bugs, ideas, or general feedback.
From grimoire
Architect documentation systems using the Divio four-quadrant model (tutorials, how-to guides, explanation, reference) to serve users at every stage.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireHow this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:design-documentation-architectureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Architect a documentation system that serves users at every stage of their journey — from first contact through expert use — using a principled structural framework.
Organizes project documentation using the Diátaxis framework (tutorials, how-to guides, reference, explanation). Use when restructuring docs to reduce support requests and improve reader navigation.
Guides project documentation structure, content requirements, and best practices. Includes templates for README, ARCHITECTURE, API docs, and change history.
Generates API documentation, architecture diagrams (C4/Mermaid), READMEs, code comments, and technical writing from codebases.
Share bugs, ideas, or general feedback.
Architect a documentation system that serves users at every stage of their journey — from first contact through expert use — using a principled structural framework.
Adopted by: Django, NumPy, Gatsby, Ansible, and hundreds of major open-source projects use the Divio system; Google Developer Documentation Style Guide is mandatory for all Google developer docs and adopted by Stripe, Twilio, and Cloudflare. Impact: Projects that adopt structured documentation architecture see 50–70% reduction in support tickets for documented features; Divio system adoption correlates with measurably higher developer satisfaction scores in API surveys. Why best: Most documentation fails because it conflates different user needs — the Divio four-quadrant model separates these needs structurally, preventing the most common documentation antipatterns.
Sources: Procida "The documentation system" (divio.com, 2017); Google Developer Documentation Style Guide (developers.google.com); Strimling "Every Page is Page One" (2014).
Audit existing documentation — inventory all existing content by type, audience, and maintenance status. Identify gaps, duplicates, and outdated material before designing.
Map user journeys — identify the four user states from the Divio model: learning (needs tutorials), doing a specific task (needs how-to guides), understanding (needs explanation/concepts), referencing (needs API/reference docs).
Apply the four-quadrant architecture — structure your documentation into: Tutorials (learning-oriented, practical), How-to Guides (problem-oriented, practical), Explanation (understanding-oriented, theoretical), Reference (information-oriented, theoretical). Never mix quadrants in a single document.
Define the information hierarchy — establish three-level maximum depth: product → domain → topic. Users should reach any page within 3 clicks from the homepage.
Design the navigation system — primary nav: Tutorials, How-to Guides, Reference, Explanation. Secondary nav: domain-specific sections. Never use jargon in nav labels.
Establish content ownership and templates — assign a maintainer to each section; create standard templates for each document type (tutorial template, how-to template, reference template, concept page template).
Define the toolchain — select documentation generator (Sphinx, MkDocs, Docusaurus, Mintlify), hosting platform, versioning strategy, and contribution workflow before writing content.
Set up search and discoverability — implement full-text search with metadata tagging. Every page needs: title, description, keywords, audience level, and last-updated date.
Create a style guide — document: voice and tone (second person, active voice), code formatting conventions, screenshot standards, link policy, and update/review cadence.
Plan for maintenance — define a review schedule (quarterly minimum), broken-link monitoring, version deprecation policy, and feedback collection mechanism (inline ratings, GitHub issues).