documentation-structure
SKILL.md
Documentation Structure
Build comprehensive, navigable documentation with clear information architecture and consistent patterns.
When to Use This Skill
- Creating documentation for a new project
- Reorganizing existing documentation
- Building documentation sites
- Writing technical guides and tutorials
- Establishing documentation standards
Documentation Information Architecture
The Four Types of Documentation
┌─────────────────────────────────────────────────────────────────┐
│ DOCUMENTATION TYPES │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ TUTORIALS │ │ HOW-TO GUIDES │ │
│ │ │ │ │ │
│ │ Learning- │ │ Problem- │ │
│ │ oriented │ │ oriented │ │
│ │ │ │ │ │
│ │ "Learn by │ │ "How do I...?" │ │
│ │ doing" │ │ │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ EXPLANATION │ │ REFERENCE │ │
│ │ │ │ │ │
│ │ Understanding- │ │ Information- │ │
│ │ oriented │ │ oriented │ │
│ │ │ │ │ │
│ │ "Why does │ │ "What are │ │
│ │ this...?" │ │ the specs?" │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Documentation Type Guidelines
| Type | Purpose | Audience | Style |
|---|---|---|---|
| Tutorials | Teach concepts through practice | New users | Hand-holding, step-by-step |
| How-To Guides | Solve specific problems | Users with context | Goal-oriented, practical |
| Explanation | Provide understanding | Curious users | Discursive, conceptual |
| Reference | Describe the system | All users | Accurate, complete |
Standard Documentation Structure
Project Documentation Layout
docs/
├── index.md # Home page / overview
├── getting-started/
│ ├── index.md # Getting started overview
│ ├── installation.md # Installation guide
│ ├── quickstart.md # Quick start tutorial
│ └── first-steps.md # First steps tutorial
├── tutorials/
│ ├── index.md # Tutorials overview
│ ├── beginner/
│ │ ├── tutorial-1.md
│ │ └── tutorial-2.md
│ └── advanced/
│ ├── tutorial-1.md
│ └── tutorial-2.md
├── guides/
│ ├── index.md # How-to guides overview
│ ├── configuration.md # How to configure
│ ├── deployment.md # How to deploy
│ ├── migration.md # How to migrate
│ └── troubleshooting.md # Common issues
├── concepts/
│ ├── index.md # Concepts overview
│ ├── architecture.md # System architecture
│ ├── core-concepts.md # Core concepts explained
│ └── glossary.md # Terminology
├── reference/
│ ├── index.md # Reference overview
│ ├── api/
│ │ ├── index.md # API overview
│ │ └── endpoints.md # API endpoints
│ ├── cli.md # CLI reference
│ ├── configuration.md # Configuration reference
│ └── changelog.md # Version history
├── contributing/
│ ├── index.md # Contributing overview
│ ├── development.md # Development setup
│ ├── style-guide.md # Code style guide
│ └── release-process.md # Release process
└── about/
├── license.md # License information
└── acknowledgments.md # Credits
README Structure
# Project Name
Brief, compelling description of what the project does.
## Features
- Feature 1
- Feature 2
- Feature 3
## Installation
```bash
pip install project-name
Quick Start
from project import main_function
result = main_function()
Documentation
Full documentation available at [docs link].
Contributing
See CONTRIBUTING.md.
License
[License type] - see LICENSE for details.
## Page Templates
### Getting Started Page
```markdown
# Getting Started
Welcome to [Project Name]! This guide will help you get up and running quickly.
## Prerequisites
Before you begin, ensure you have:
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3
## Installation
### Option 1: pip (Recommended)
```bash
pip install project-name
Option 2: From Source
git clone https://github.com/org/project.git
cd project
pip install -e .
Verify Installation
project --version
Next Steps
- Quick Start Tutorial - Build your first example
- Core Concepts - Understand the fundamentals
- Configuration Guide - Customize your setup
### Tutorial Template
```markdown
# Tutorial: [Action/Goal]
**Time to complete**: ~15 minutes
**Prerequisites**: [List any required knowledge/setup]
## What You'll Learn
By the end of this tutorial, you will:
- Learning outcome 1
- Learning outcome 2
- Learning outcome 3
## Overview
[Brief explanation of what we're building and why]
## Step 1: [Action]
[Explanation of what we're doing]
```python
# code example
[Explanation of what happened]
Step 2: [Action]
[Continue pattern...]
Step 3: [Action]
[Continue pattern...]
Verify Your Work
To confirm everything is working:
# verification command
You should see:
expected output
What's Next?
Congratulations! You've completed [tutorial name].
- Next Tutorial - Continue learning
- Related Concept - Understand the theory
- Reference - Full API details
Troubleshooting
Issue 1: [Common Problem]
Solution: [How to fix]
Issue 2: [Common Problem]
Solution: [How to fix]
### How-To Guide Template
```markdown
# How to [Accomplish Task]
This guide shows you how to [task description].
## Prerequisites
- Prerequisite 1
- Prerequisite 2
## Steps
### 1. [First Step]
```bash
command or code
2. [Second Step]
code example
3. [Third Step]
[Instructions...]
Complete Example
# Full working example
Related
### Reference Page Template
```markdown
# [Component] Reference
Complete reference for [component].
## Overview
[Brief description of the component]
## [Section 1]
### `function_name(param1, param2)`
Description of the function.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `param1` | `str` | Yes | Description |
| `param2` | `int` | No | Description (default: 10) |
**Returns:** `ReturnType` - Description of return value
**Raises:**
- `ValueError` - When [condition]
- `TypeError` - When [condition]
**Example:**
```python
result = function_name("value", param2=20)
[Section 2]
[Continue pattern...]
See Also
## Writing Guidelines
### Voice and Tone
| Context | Tone | Example |
|---------|------|---------|
| **Tutorials** | Friendly, encouraging | "Great job! Now let's..." |
| **How-To Guides** | Direct, practical | "To configure X, do Y" |
| **Concepts** | Explanatory, thorough | "This works because..." |
| **Reference** | Precise, factual | "Returns X when Y" |
### Formatting Standards
#### Headings
```markdown
# Page Title (H1) - One per page
## Major Section (H2)
### Subsection (H3)
#### Minor Section (H4) - Use sparingly
Code Blocks
Use fenced code blocks with language identifier:
```python
def example():
pass
For shell commands:
pip install package
For output/results:
Expected output here
#### Callouts/Admonitions
```markdown
> **Note**: Additional information that's helpful but not critical.
> **Warning**: Important information that could cause problems if ignored.
> **Tip**: Helpful suggestion to improve workflow.
> **Important**: Critical information that must be understood.
Lists
Use bullet lists for unordered items:
- Item 1
- Item 2
- Item 3
Use numbered lists for sequential steps:
1. First step
2. Second step
3. Third step
Use definition lists for term/definition pairs:
Term 1
: Definition of term 1
Term 2
: Definition of term 2
Content Guidelines
Do's
- ✅ Start pages with a clear purpose statement
- ✅ Use consistent terminology (define in glossary)
- ✅ Include working code examples
- ✅ Provide context before details
- ✅ Link to related content
- ✅ Keep paragraphs short (3-4 sentences)
- ✅ Use active voice
- ✅ Include "what's next" sections
Don'ts
- ❌ Assume prior knowledge without stating prerequisites
- ❌ Mix documentation types (don't explain concepts in tutorials)
- ❌ Use jargon without defining it
- ❌ Write walls of text without formatting
- ❌ Leave code examples untested
- ❌ Use ambiguous pronouns ("it", "this", "that")
Navigation Patterns
Breadcrumbs
[Home](../index.md) > [Guides](index.md) > Configuration
Previous/Next Navigation
---
← Previous: [Installation](installation.md) | Next: [First Steps](first-steps.md) →
Related Content
## See Also
- [Related Guide 1](guide1.md) - When to use this
- [Related Concept](../concepts/topic.md) - Understanding why
- [API Reference](../reference/api.md) - Full details
Table of Contents
For longer pages, include a TOC:
## Contents
- [Overview](#overview)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)
Documentation Checklist
## New Documentation Checklist
### Structure
- [ ] Follows standard directory layout
- [ ] Placed in correct documentation type folder
- [ ] Linked from parent index page
- [ ] Added to navigation/sidebar
### Content
- [ ] Clear title describing the content
- [ ] Opening paragraph explains purpose
- [ ] Prerequisites listed (if applicable)
- [ ] Code examples are complete and tested
- [ ] Screenshots/diagrams where helpful
- [ ] Related content linked
- [ ] Next steps provided
### Quality
- [ ] Proofread for spelling/grammar
- [ ] Technical accuracy verified
- [ ] Links tested
- [ ] Code examples run successfully
- [ ] Consistent with style guide
### Accessibility
- [ ] Images have alt text
- [ ] Code blocks have language identifiers
- [ ] Headings are hierarchical
- [ ] Color is not only indicator
Resources
- Diátaxis Framework - Documentation system
- Write the Docs - Documentation community
- Google Developer Documentation Style Guide
- Microsoft Writing Style Guide
Guidelines
- Organize by user need, not by system structure
- Keep the four documentation types separate
- Always start with who the reader is and what they need
- Test all code examples before publishing
- Review and update documentation with each release
- Use consistent terminology across all documentation
- Provide clear navigation and cross-references
- Include troubleshooting for common issues
Weekly Installs
1
Repository
franciscosanche…factu-esFirst Seen
13 days ago
Security Audits
Installed on
mcpjam1
claude-code1
junie1
windsurf1
zencoder1
crush1