Home > Contributing > Documentation
How to write documentation for KnowStack following the Diátaxis framework.
KnowStack documentation follows the Diátaxis framework - a systematic approach to technical documentation that organizes content into four distinct quadrants.
Research Sources:
- Diátaxis - The framework specification
- Divio Documentation System - Original implementation
- Documentation Best Practices - Modular content principles
PRACTICAL THEORETICAL
┌─────────────────────────────────────────────────────┐
│ │
LEARNING │ TUTORIALS │ EXPLANATION │
│ (Learning-oriented)│ (Understanding-oriented)│
│ "Follow these │ "Here's why this │
│ steps to learn" │ works this way" │
│ │ │
├──────────────────────┼──────────────────────────────┤
│ │ │
WORKING │ HOW-TO GUIDES │ REFERENCE │
│ (Task-oriented) │ (Information-oriented) │
│ "How to solve │ "Technical specs │
│ this problem" │ and details" │
│ │ │
└─────────────────────────────────────────────────────┘
Purpose: Learning-oriented, for beginners
Characteristics:
- Step-by-step instructions
- Has a clear beginning, middle, end
- Produces a working result
- Teaches concepts through practice
- No prerequisites beyond basic setup
File naming: verb-noun.md or noun.md
quick-start.md
Example structure:
# Tutorial Title
Brief intro of what you'll learn.
## Prerequisites
What the reader needs before starting.
## Step 1: First Action
Instructions...
## Step 2: Next Action
Instructions...
## Congratulations!
Summary of what was accomplished.
## Next Steps
Links to related content.Purpose: Task-oriented, for practitioners
Characteristics:
- Solves a specific problem
- Assumes some familiarity
- "How to X" format
- Multiple ways to achieve goal
- Links to reference for details
File naming: noun.md (the thing being managed)
backfill-embeddings.md
Example structure:
# Guide Title
Brief overview of what this guide covers.
## Overview
Context and when to use this.
## Doing the Task
Step-by-step instructions with examples.
## Common Variations
Alternative approaches if applicable.
## See Also
- Links to related guides
- Links to reference docsPurpose: Information-oriented, for practitioners
Characteristics:
- Exhaustive and accurate
- Consistent format
- No explanation of "why"
- Easy to scan/search
- Tables, schemas, examples
File naming: noun.md (the thing being documented)
api/mcp.mdconfiguration/settings.mdconfiguration/embedding.md
Example structure:
# Reference Title
Brief description of what this documents.
## Endpoint/Entity Name
### Method/Field
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `field` | type | Yes/No | Description |
### Example
\`\`\`json
{ "example": "data" }
\`\`\`
## See Also
- Links to related reference
- Links to guides for "how to"Purpose: Understanding-oriented, for learners
Characteristics:
- Explains concepts and decisions
- Provides context and background
- Connects ideas together
- No step-by-step instructions
- Answers "why" questions
File naming: noun.md (the concept)
concepts/multi-tenancy.mdconcepts/semantic-retrieval.mdarchitecture/patterns.md
Example structure:
# Concept Title
Introduction to the concept.
## Overview
What it is and why it matters.
## How It Works
Conceptual explanation (not step-by-step).
## Design Decisions
Why it's implemented this way.
## See Also
- Links to related concepts
- Links to guides for practical usedocs/
├── index.md # Navigation hub
├── tutorials/ # Learning by doing
│ └── index.md # List of tutorials
├── guides/ # Task completion
│ ├── index.md # List of guides
│ └── integrations/ # Integration-specific guides
├── reference/ # Technical specs
│ ├── index.md # Reference overview
│ └── api/ # API endpoint specs
├── explanation/ # Understanding
│ ├── index.md # Explanation overview
│ ├── concepts/ # Core concepts
│ └── architecture/ # System design
├── agents/ # AI agent definitions (seeded as PUBLIC)
├── skills/ # Skill definitions (seeded as PUBLIC)
├── commands/ # Command definitions (seeded as PUBLIC)
├── templates/ # Template definitions (seeded as PUBLIC)
├── contributing/ # Contributor docs
└── about/ # Business/product info
Every file must end with a "See Also" section:
## See Also
- [Related Guide](../guides/related.md) - Brief description
- [Related Reference](../reference/api/related.md) - Brief description| From | Link To | Purpose |
|---|---|---|
| Tutorial | Next tutorial, Reference | "Learn more", "Full spec" |
| Guide | Reference, Explanation | "API details", "Background" |
| Reference | Guide, Related reference | "How to use", "Related" |
| Explanation | Guide, Reference | "In practice", "Specification" |
Always use relative paths:
# From docs/guides/backfill-embeddings.md
[Embedding Configuration](../reference/configuration/embedding.md)
[Semantic Retrieval](../explanation/concepts/semantic-retrieval.md)
# From docs/reference/api/mcp.md
[Backfill Guide](../../guides/backfill-embeddings.md)- Use sentence case: "Getting started" not "Getting Started"
- Exception: Proper nouns ("GitHub App")
- Always include working examples
- Show both request and response
- Use realistic but obviously fake data
- Use tables for structured data (parameters, fields, options)
- Include Type and Required columns for API docs
- Time estimates ("this takes 5 minutes")
- Subjective language ("easy", "simple", "just")
- Duplicate content - link instead
- Outdated information - verify against code
When adding a new feature, create:
- Reference (
reference/api/feature.md) - Endpoint specs - Guide (
guides/feature.md) - How to use it - Explanation (
explanation/concepts/feature.md) - If new concept
- Add to
tutorials/with clear prerequisites - Update
tutorials/index.md - Link from relevant guides
- Update the source file
- Check all cross-references still work
- Update related files if scope changed
Before committing documentation changes:
- Links work - All internal links resolve
- Code works - Examples are accurate
- Cross-refs exist - Every file has "See Also"
- Index updated - New files listed in index.md
- Quadrant correct - Content matches its category
- Development Setup - Local environment
- Adding Features - Code guidelines