From 34ad0d8f98fd8a7342cd59ab09003f6bae562a56 Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Sat, 12 Sep 2026 17:51:58 -0400 Subject: [PATCH] feat(trogonstack-diataxis): make documentation easier to write and maintain Signed-off-by: Yordis Prieto --- plugins/trogonstack-diataxis/README.md | 6 +- .../skills/diataxis-organize-docs/SKILL.md | 216 ++---------------- .../references/classification.md | 103 +++++++++ .../references/navigation.md | 37 +++ .../references/splitting.md | 43 ++++ .../skills/diataxis-write-docs/SKILL.md | 53 +++++ .../references/explanation.md | 20 ++ .../diataxis-write-docs/references/how-to.md | 20 ++ .../references/reference.md | 20 ++ .../references/tutorial.md | 20 ++ 10 files changed, 341 insertions(+), 197 deletions(-) create mode 100644 plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/classification.md create mode 100644 plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/navigation.md create mode 100644 plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/splitting.md create mode 100644 plugins/trogonstack-diataxis/skills/diataxis-write-docs/SKILL.md create mode 100644 plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/explanation.md create mode 100644 plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/how-to.md create mode 100644 plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/reference.md create mode 100644 plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/tutorial.md diff --git a/plugins/trogonstack-diataxis/README.md b/plugins/trogonstack-diataxis/README.md index 94e6818..9bc522d 100644 --- a/plugins/trogonstack-diataxis/README.md +++ b/plugins/trogonstack-diataxis/README.md @@ -1,7 +1,9 @@ # trogonstack-diataxis -Documentation skills following the Diataxis framework for organizing and generating docs into tutorials, how-to guides, reference, and explanation sections. +Diataxis guidance for writing and organizing documentation around the reader's needs. ```bash claude plugin install trogonstack-diataxis@trogonstack -``` \ No newline at end of file +``` + +Use [diataxis-write-docs](skills/diataxis-write-docs/SKILL.md) to draft or revise documentation for its intended audience. Use [diataxis-organize-docs](skills/diataxis-organize-docs/SKILL.md) to classify, split, or relocate existing material and maintain its navigation. diff --git a/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/SKILL.md b/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/SKILL.md index 5b2d2e4..26660f3 100644 --- a/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/SKILL.md +++ b/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/SKILL.md @@ -8,9 +8,9 @@ allowed-tools: # Diataxis Documentation Organization -Reorganize documentation by classifying content into the four Diataxis quadrants and creating a structured documentation hierarchy. +Reorganize documentation by classifying content into the Diataxis categories and creating a structured documentation hierarchy. -## The Four Quadrants +## Documentation Categories | Quadrant | Orientation | Purpose | User Need | |----------|-------------|---------|-----------| @@ -19,25 +19,13 @@ Reorganize documentation by classifying content into the four Diataxis quadrants | **Reference** | Information | Describe the machinery | "I need facts about Y" | | **Explanation** | Understanding | Clarify concepts | "I want to understand why" | -## Step 1: Analyze Existing Documentation +## Directory Structure -Scan the documentation directory and classify each file or section: +Organize docs into this hierarchy, adding topic subdirectories as needed: -``` -For each document/section, determine: -- Does it walk through steps to learn? → Tutorial -- Does it solve a specific problem? → How-to -- Does it describe APIs/configs/specs? → Reference -- Does it explain concepts/rationale? → Explanation -``` - -## Step 2: Create Directory Structure - -Organize docs into this hierarchy: - -``` +```text docs/ -├── tutorials/ # Learning-oriented +├── tutorial/ # Learning-oriented │ ├── getting-started/ │ └── {topic}/ ├── how-to/ # Task-oriented @@ -54,191 +42,29 @@ docs/ └── README.md # Navigation hub ``` -## Step 3: Classification Criteria - -### Tutorials (Learning) - -**Characteristics:** -- Step-by-step instructions for beginners -- Builds toward a working example -- Focuses on "what the user does" -- Has a concrete end goal - -**Example titles:** -- "Your First Application" -- "Getting Started with X" -- "Building a Sample Project" - -**DO NOT include:** -- Exhaustive options or configurations -- Theoretical explanations -- Edge cases - -### How-to Guides (Tasks) - -**Characteristics:** -- Assumes basic knowledge -- Addresses a specific problem -- Provides actionable steps -- May have multiple valid approaches - -**Example titles:** -- "How to Deploy to Production" -- "Migrating from v1 to v2" -- "Configuring Authentication" - -**DO NOT include:** -- Teaching fundamentals -- Complete API documentation -- Philosophical discussions - -### Reference (Information) - -**Characteristics:** -- Accurate and complete -- Consistent structure -- Describes what IS (not how to use) -- Dry, factual tone - -**Example content:** -- API endpoints and parameters -- Configuration options -- CLI commands and flags -- Data schemas - -**DO NOT include:** -- Explanations of why -- Step-by-step tutorials -- Opinions or recommendations - -### Explanation (Understanding) - -**Characteristics:** -- Discusses context and background -- Explains design decisions -- Connects concepts together -- Can be discursive - -**Example titles:** -- "Understanding the Event Loop" -- "Why We Chose X over Y" -- "Architecture Overview" - -**DO NOT include:** -- How-to instructions -- Reference specifications -- Beginner tutorials - -## Step 4: Split Mixed Documents - -When a document contains multiple types: - -1. **Identify boundaries** - Mark where content shifts purpose -2. **Extract sections** - Move each type to its proper location -3. **Add cross-references** - Link related content across quadrants -4. **Preserve context** - Ensure each piece stands alone - -### Example Split - -**Before (mixed document):** -```markdown -# Authentication - -Authentication uses JWT tokens. (explanation) - -## Quick Start -1. Install the package... (tutorial) - -## API Reference -- `authenticate(user, pass)` - Returns token (reference) - -## Troubleshooting -### Token Expired -If you see error X, do Y... (how-to) -``` - -**After (split):** -``` -tutorials/authentication-quickstart.md -how-to/troubleshooting/token-expired.md -reference/api/authentication.md -explanation/concepts/authentication.md -``` - -## Step 5: Create Navigation Index - -Always use `README.md` as the root navigation file — never `index.md`. +Always use `docs/README.md` as the root navigation file, never `index.md`. -Build a documentation hub that helps users find content by their need: +## Writing Conventions -```markdown -# Documentation +Keep skill instructions and generated documentation free of manually maintained totals and numbered section references. Use descriptive headings and named links. For ordered procedures, write each Markdown list marker as `1.` so the renderer maintains numbering. Preserve numeric facts that are necessary to understand or use the subject. -## Learning -New here? Start with our tutorials: -- [Getting Started](tutorials/getting-started.md) -- [Your First App](tutorials/first-app.md) +## Workflow -## Guides -Solve specific problems: -- [Deployment](how-to/deployment/) -- [Troubleshooting](how-to/troubleshooting/) +Load only the references needed for the current task: -## Reference -Technical specifications: -- [API Reference](reference/api/) -- [Configuration](reference/configuration/) +1. **Analyze existing content.** Classify each file or section by the reader's need. Read [classification criteria](references/classification.md) when classifying existing content or resolving ambiguous categories. +1. **Map the structure.** Assign content to the hierarchy above and identify which documents to keep, move, or split. +1. **Separate mixed documents.** When a document serves multiple purposes, read [splitting guidance](references/splitting.md) for the migration procedure and example. Preserve context and link related content across quadrants. +1. **Build navigation.** When creating or updating the documentation hub, read [navigation guidance](references/navigation.md) for its template. Update links affected by moved or split content. +1. **Verify and report.** Apply the completion checks below. For an audit, report the current state, classifications, proposed file placements, and needed cross-references. For completed edits, summarize the changes and verification. Scale the report to the task. -## Understanding -Deep dives and background: -- [Architecture](explanation/architecture.md) -- [Design Decisions](explanation/decisions/) -``` +## Completion Checks -## Quality Checklist - -After reorganization, verify: - -- [ ] Each document serves ONE purpose +- [ ] Each document serves one purpose - [ ] Tutorials have clear learning outcomes - [ ] How-to guides solve specific problems - [ ] Reference is complete and accurate - [ ] Explanations provide genuine insight -- [ ] Cross-references connect related content -- [ ] Navigation makes user intent clear -- [ ] No orphaned or duplicated content - -## Anti-Patterns to Fix - -| Problem | Solution | -|---------|----------| -| Tutorial with exhaustive options | Move options to reference, link to it | -| How-to explaining fundamentals | Extract to tutorial, assume knowledge | -| Reference with usage examples | Move examples to how-to | -| Explanation with code snippets | Keep only conceptual snippets | -| One giant README | Split into proper quadrants | - -## Output Format - -After analysis, report: - -```markdown -## Documentation Audit - -### Current State -- Total documents: X -- Mixed documents: Y -- Missing quadrants: [list] - -### Classification Results -| Document | Current Type | Recommended Type | Action | -|----------|--------------|------------------|--------| -| ... | ... | ... | Split/Move/Keep | - -### Proposed Structure -[Directory tree with file placements] - -### Cross-References Needed -- [doc A] should link to [doc B] -- ... -``` +- [ ] Cross-references connect related content and resolve after moves +- [ ] `docs/README.md` makes user intent clear +- [ ] No orphaned, duplicated, or lost content diff --git a/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/classification.md b/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/classification.md new file mode 100644 index 0000000..f42abc6 --- /dev/null +++ b/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/classification.md @@ -0,0 +1,103 @@ +# Classification Criteria + +Classify each document or section by its purpose: + +- Does it walk through steps to learn? Tutorial. +- Does it solve a specific problem? How-to. +- Does it describe APIs, configurations, or specifications? Reference. +- Does it explain concepts or rationale? Explanation. + +## Tutorials (Learning) + +**Characteristics:** + +- Step-by-step instructions for learners +- Builds toward a working example +- Focuses on "what the user does" +- Has a concrete end goal + +**Example titles:** + +- "Your First Application" +- "Getting Started with X" +- "Building a Sample Project" + +**DO NOT include:** + +- Exhaustive options or configurations +- Theoretical explanations +- Edge cases + +## How-to Guides (Tasks) + +**Characteristics:** + +- Assumes basic knowledge +- Addresses a specific problem +- Provides actionable steps +- May have multiple valid approaches + +**Example titles:** + +- "How to Deploy to Production" +- "Migrating from v1 to v2" +- "Configuring Authentication" + +**DO NOT include:** + +- Teaching fundamentals +- Complete API documentation +- Philosophical discussions + +## Reference (Information) + +**Characteristics:** + +- Accurate and complete +- Consistent structure +- Describes interfaces, behavior, and constraints +- Dry, factual tone + +**Example content:** + +- API endpoints and parameters +- Configuration options +- CLI commands and flags +- Data schemas + +**DO NOT include:** + +- Explanations of why +- Step-by-step tutorials +- Opinions or recommendations + +## Explanation (Understanding) + +**Characteristics:** + +- Discusses context and background +- Explains design decisions +- Connects concepts together +- Can be discursive + +**Example titles:** + +- "Understanding the Event Loop" +- "Why We Chose X over Y" +- "Architecture Overview" + +**DO NOT include:** + +- How-to instructions +- Reference specifications +- Learning walkthroughs + +## Anti-Patterns to Fix + +| Problem | Solution | +|---------|----------| +| Tutorial with exhaustive options | Move options to reference, link to it | +| How-to explaining fundamentals | Extract to tutorial, assume knowledge | +| Reference with a task walkthrough | Move the walkthrough to how-to; keep concise usage examples | +| Explanation dominated by procedural code | Move the procedure to how-to; keep snippets that clarify concepts | +| One giant README | Split into proper quadrants | diff --git a/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/navigation.md b/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/navigation.md new file mode 100644 index 0000000..5cf638a --- /dev/null +++ b/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/navigation.md @@ -0,0 +1,37 @@ +# Documentation Navigation + +Build a documentation hub that helps users find content by their need. Adapt this template for `docs/README.md`, using links to content that exists in the resulting structure. + +```markdown +# Documentation + +## Learning + +New here? Start with our tutorials: + +- [Getting Started](tutorial/getting-started/README.md) +- [Your First App](tutorial/getting-started/first-app.md) + +## Guides + +Solve specific problems: + +- [Deployment](how-to/deployment/) +- [Troubleshooting](how-to/troubleshooting/) + +## Reference + +Technical specifications: + +- [API Reference](reference/api/) +- [Configuration](reference/configuration/) + +## Understanding + +Deep dives and background: + +- [Architecture](explanation/concepts/architecture.md) +- [Design Decisions](explanation/decisions/) +``` + +Keep the hub's links consistent with the final file placements. Ensure every document is reachable through the hub or related pages, and verify links to moved files and sections. diff --git a/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/splitting.md b/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/splitting.md new file mode 100644 index 0000000..39761bb --- /dev/null +++ b/plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/splitting.md @@ -0,0 +1,43 @@ +# Split Mixed Documents + +When a document contains multiple types: + +1. **Identify boundaries.** Mark where content shifts purpose. +1. **Extract sections.** Move each type to its proper location. +1. **Add cross-references.** Link related content across quadrants and update links to moved sections. +1. **Preserve context.** Ensure each piece stands alone and all original content is accounted for. + +## Example Split + +**Before (mixed document):** + +```markdown +# Authentication + +Authentication uses JWT tokens. (explanation) + +## Quick Start + +1. Install the package... (tutorial) + +## API Reference + +- `authenticate(user, pass)` - Returns token (reference) + +## Troubleshooting + +### Token Expired + +If you see error X, do Y... (how-to) +``` + +**After (paths relative to `docs/`):** + +```text +tutorial/authentication/quickstart.md +how-to/troubleshooting/token-expired.md +reference/api/authentication.md +explanation/concepts/authentication.md +``` + +Link the quickstart to the authentication reference and explanation. Link the troubleshooting guide to the token details in the reference, so readers can find related information without duplicating it. diff --git a/plugins/trogonstack-diataxis/skills/diataxis-write-docs/SKILL.md b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/SKILL.md new file mode 100644 index 0000000..44ff0d6 --- /dev/null +++ b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/SKILL.md @@ -0,0 +1,53 @@ +--- +name: diataxis-write-docs +description: Draft or revise project documentation for the reader's purpose using Diataxis. Use for writing tutorials, how-to guides, reference, or explanation; use diataxis-organize-docs for reorganizing an existing documentation collection. +allowed-tools: + - Read + - Write +--- + +# Diataxis Documentation Writing + +Write documentation that answers a specific reader need and reflects the project's actual behavior. This workflow works independently of documentation reorganization. + +## Choose the Reader Need + +Identify the audience, assumed knowledge, desired outcome, and requested scope from the task and available material. Ask only when missing information would materially change the document. + +Choose by purpose, not topic difficulty or the presence of code. Read the matching reference when drafting or revising that type; load additional references only for additional requested document types. + +| Reader need | Document type | Writing guidance | +|-------------|---------------|------------------| +| Learn through a guided exercise | Tutorial | [Tutorial writing](references/tutorial.md) | +| Accomplish a particular task | How-to | [How-to writing](references/how-to.md) | +| Look up precise information | Reference | [Reference writing](references/reference.md) | +| Understand a concept or rationale | Explanation | [Explanation writing](references/explanation.md) | + +For a mixed request, give each document a primary purpose and connect related material with links. Preserve the user's requested deliverables. A request to draft a page does not require reorganizing the collection first. + +## Establish the Evidence + +Inspect the relevant implementation, schemas, tests, existing documentation, and maintained project examples. Match external documentation to the project's version and dependencies. Use available project discovery tools when provided. + +Resolve conflicting sources before making a definitive claim. Distinguish implemented behavior from proposals, intentions, and assumptions. Do not invent commands, API signatures, defaults, output, or design rationale to complete a draft. Narrow unsupported claims or ask for the missing information when it prevents a useful result. + +## Draft or Revise + +Apply the selected reference's writing guidance and anti-pattern checks. Make the title and opening identify the reader's goal, then include the detail needed to achieve it. Preserve useful existing content and project terminology during revision. + +Keep instructions and generated documentation free of manually maintained totals and numbered section references. Use descriptive headings and named links. For actual ordered procedures, write every Markdown list marker as `1.` so the renderer maintains numbering. Preserve necessary numeric facts such as versions, limits, and measured values. + +## Place and Connect + +Honor the requested destination and existing documentation conventions. For a new documentation collection without an established layout, use `docs/tutorial/`, `docs/how-to/`, `docs/reference/`, and `docs/explanation/`, with `docs/README.md` as the navigation hub. Create only the directories the requested documents need. + +Add relevant navigation links when maintaining the collection is within scope, and repair links affected by your edits. Link only to known destinations. When draft pages have no assigned paths, report suggested cross-references in the delivery note instead of adding speculative paths or cross-document anchors. Leave unrelated files and organization alone. Use `diataxis-organize-docs` when the user also requests collection restructuring. + +## Verify and Deliver + +- Check claims, identifiers, and example inputs against the evidence and declared version. +- Exercise executable examples when available tools, environment, and authorization permit. Otherwise inspect them against source and report that they were not run. Label conceptual snippets as illustrative when readers could mistake them for executable examples. +- Check affected links, anchors, and any applicable documentation build using available tools. +- Confirm the document satisfies the selected reader need without unnecessary digressions. + +Deliver the requested documentation with a concise account of verification and any remaining evidence gaps. Do not present static inspection as execution or a proposed design as shipped behavior. diff --git a/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/explanation.md b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/explanation.md new file mode 100644 index 0000000..b35d2ee --- /dev/null +++ b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/explanation.md @@ -0,0 +1,20 @@ +# Explanation Writing + +Answer a bounded conceptual or design question. Follow [Diataxis on explanation](https://diataxis.fr/explanation/). + +## Develop Understanding + +State the question and its relevance. Connect concepts, relationships, context, and consequences under descriptive headings. + +Discuss alternatives and trade-offs when they illuminate the subject. Attribute recorded decisions to their evidence. Distinguish documented historical rationale from your analysis of the current design; source code alone does not establish why an author chose it. + +Use diagrams, analogies, and conceptual code snippets to clarify relationships. State meaningful limits of analogies. Link operational procedures and detailed contracts for action or lookup. + +## Anti-Patterns + +| Problem | Writing correction | +|---------|--------------------| +| An unbounded topic becomes a survey of everything | Center the document on a clear question | +| A sequence of commands replaces reasoning | Explain relationships and link task instructions | +| An inferred motivation becomes historical fact | Identify it as analysis or find the decision record | +| Code is removed solely because this is explanation | Keep conceptual snippets that support understanding | diff --git a/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/how-to.md b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/how-to.md new file mode 100644 index 0000000..ca50500 --- /dev/null +++ b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/how-to.md @@ -0,0 +1,20 @@ +# How-to Writing + +Help a reader achieve a known practical outcome. Follow [Diataxis on how-to guides](https://diataxis.fr/how-to-guides/). + +## Guide the Task + +Name the task in the title. Establish applicability, the starting state, and completion criteria. Assume relevant competence; link foundational knowledge instead of teaching it inline. + +Arrange actions around the reader's work and its dependencies. Use an ordered procedure where sequence matters. When the task requires judgment, give decision criteria and conditional paths with descriptive headings. A useful guide may have different entry and exit points. + +Include supported failure handling and recovery. Explain necessary consequences before the affected action. Link exhaustive options and extended rationale separately. + +## Anti-Patterns + +| Problem | Writing correction | +|---------|--------------------| +| A tour of features lacks a reader goal | Frame the guide around a specific outcome | +| A long introductory lesson delays action | State assumed knowledge and link learning material | +| A rigid recipe hides meaningful branches | Identify the condition and action for each relevant path | +| A catalog of options overwhelms the task | Include needed choices and link the full reference | diff --git a/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/reference.md b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/reference.md new file mode 100644 index 0000000..19796c4 --- /dev/null +++ b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/reference.md @@ -0,0 +1,20 @@ +# Reference Writing + +Support precise lookup of interfaces and behavior. Follow [Diataxis on reference](https://diataxis.fr/reference/). + +## Describe the Contract + +Define the interface and version. Mirror the system's structure for lookup without sequential reading. Use a consistent entry structure. + +For APIs, configuration, or commands, document relevant signatures, types, units, required values, defaults, constraints, effects, and errors from authoritative evidence. Cover the promised scope rather than asserting completeness for an unexamined system. Distinguish supported guarantees from incidental implementation details. + +Include concise examples illustrating an entry, syntax, or constraint. Examples belong here when they aid lookup. Link task workflows and learning journeys separately. + +## Anti-Patterns + +| Problem | Writing correction | +|---------|--------------------| +| A default or guarantee is guessed from its name | Verify it against the relevant contract or implementation | +| A lookup entry becomes a guided project | Retain the focused example and link the workflow | +| Every usage example is removed | Keep illustrations that clarify the documented entry | +| Recommendations obscure factual behavior | State the contract and link decision guidance separately | diff --git a/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/tutorial.md b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/tutorial.md new file mode 100644 index 0000000..0195cfc --- /dev/null +++ b/plugins/trogonstack-diataxis/skills/diataxis-write-docs/references/tutorial.md @@ -0,0 +1,20 @@ +# Tutorial Writing + +Help a learner gain experience through guided activity, including advanced subjects. Follow [Diataxis on tutorials](https://diataxis.fr/tutorials/). + +## Shape the Learning Experience + +Choose a concrete exercise with meaningful practice. Introduce its outcome and the environment and prior knowledge required to start. + +Guide a reliable path with manageable actions and observable results. Explain what the learner should notice after significant actions so they can recognize progress. Make necessary choices for the exercise and link optional alternatives elsewhere. + +Keep explanations brief and connected to the activity. Close with the completed outcome and useful next learning opportunities. Include cleanup or reset guidance for resources left behind. + +## Anti-Patterns + +| Problem | Writing correction | +|---------|--------------------| +| Every option appears before the learner can act | Select an exercise path and link the option reference | +| Instructions depend on unstated setup | Include the prerequisites needed to reproduce the exercise | +| Long theory interrupts practical work | Keep essential orientation and link fuller explanation | +| Actions have no visible checkpoints | Describe the expected result and what to notice |