Skip to main content

Documentation Rules

This document outlines the standards and conventions for maintaining consistent documentation across all projects.

File Naming Conventions​

Directory Structure​

docs/
├── casper/                    # Internal team documentation
│   └── _category_.json
├── [project-name]/            # Project-specific docs (kebab-case)
│   ├── _category_.json
│   ├── 0000-prospecting/      # Phase directories with numeric prefix
│   │   ├── _category_.json
│   │   ├── 0000-[topic].md
│   │   ├── 0001-[topic].md
│   │   └── ...
│   ├── 0001-discovery/
│   ├── 0002-design/
│   ├── 0003-engineering/
│   └── 1000-transcripts/      # Supporting materials (high number prefix)

File Naming Rules​

ElementConventionExample
DirectoriesNNNN-phase-name (kebab-case)0000-prospecting, 1000-transcripts
DocumentsNNNN-topic-name.md (kebab-case)0001-proposal-review.md
Category files_category_.jsonAlways lowercase with underscores

Numeric Prefixes​

  • 0000-0999: Primary project phases (ordered chronologically)
  • 1000-9999: Supporting materials, transcripts, appendices

Frontmatter Requirements​

Every markdown file must include YAML frontmatter with the following fields:

---
title: "Document Title"
sidebar_position: 0
sidebar_label: "Sidebar Label"
description: "A concise description of the document content (50-160 characters ideal)."
---

Field Guidelines​

FieldRequiredDescription
title✅ YesFull document title, displayed as page title
sidebar_position✅ YesInteger matching the file's numeric prefix
sidebar_label✅ YesShort label for sidebar navigation
description✅ YesSEO-friendly summary (appears in link previews)

Examples​

Meeting Summary:

---
title: Prospect Call
sidebar_position: 0
sidebar_label: Prospect Call
description: "Initial discovery call discussing mobile app requirements, feature scope, and project timeline."
---

Transcript:

---
title: "Transcript: Prospect Call"
sidebar_position: 0
sidebar_label: "Prospect Call"
description: "Full transcript of the initial prospect call on January 15th, 2026."
---

Research Document:

---
title: Website Discovery
sidebar_position: 2
sidebar_label: Website Discovery
description: "Research on company services, technology stack, and digital presence."
---

Category Configuration​

Each directory must contain a _category_.json file:

{
  "label": "Phase Name",
  "position": 0,
  "link": {
    "type": "generated-index",
    "title": "Phase Name",
    "description": "Brief description of what this phase contains.",
    "slug": "/project-name/phase-name"
  }
}

Category Position Guidelines​

PhasePositionDescription
Prospecting0Initial outreach, calls, proposals
Discovery1Research, requirements gathering
Design2UI/UX design, visual blueprints
Engineering3Technical implementation
Transcripts1000Full meeting transcripts

Document Structure​

Meeting Summaries​

Meeting summaries should follow this structure:

# [Meeting Title]

**Meeting Date:** [Month Day, Year]  
**Attendees:** [Name 1], [Name 2], [Name 3]

---

[Optional: Embedded video/recording]

---

## Summary

| Area | Details |
|------|---------|
| **Topic 1** | Key point about topic 1 |
| **Topic 2** | Key point about topic 2 |

---

## Notes

### Section Heading

Detailed notes organized by topic...

- Bullet point with **bold emphasis** for key terms
- Supporting details and context

---

## Action Items

| Assignee | Action | Reference |
|----------|--------|-----------|
| **Name** | Action description | Timestamp or section |

---

## Resources

📝 **[Full Transcript](../1000-transcripts/NNNN-document-name.md)**

Transcript Documents​

Transcripts should follow this structure:

# [Meeting Title] Transcript

**Meeting Date:** [Month Day, Year] - [Time]
**Attendees:** [Name 1], [Name 2], [Name 3]

---

**Speaker Name** *[MM:SS]*: Transcript content...

Research Documents​

Research documents should include:

  1. Executive Summary - Brief overview
  2. Key Sections - Organized by topic with tables where appropriate
  3. Observations - Analysis and insights
  4. Generated Date - When the research was compiled

Linking Conventions​

Use relative paths for internal document links:

<!-- From 0000-prospecting/0000-prospect-call.md to transcript -->
📝 **[Full Transcript](../1000-transcripts/0000-prospect-call.md)**

<!-- From any doc to another in same directory -->
See [Related Topic](./0001-related-topic.md)

<!-- From any doc to another phase -->
See [Discovery Overview](../0001-discovery/0000-overview.md)
From → ToPath Format
Same directory./NNNN-file.md
Sibling directory../NNNN-directory/NNNN-file.md
Child directory./NNNN-directory/NNNN-file.md

Formatting Guidelines​

Text Formatting​

ElementSyntaxUse Case
Bold**text**Key terms, names, emphasis
Italic*text*Quotes, timestamps, secondary emphasis
Code`text`Technical terms, file names, commands

Tables​

Use tables for structured data:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1 | Data 2 | Data 3 |

Horizontal Rules​

Use --- to separate major sections.

Blockquotes​

Use for company information or key quotes:

> **Company:** Company Name  
> **Website:** [www.example.com](https://www.example.com)  
> **Tagline:** *"Company tagline here"*

Quality Checklist​

Before committing documentation:

  • Frontmatter is complete with all required fields
  • sidebar_position matches the file's numeric prefix
  • All internal links use correct relative paths
  • Meeting summaries include date, attendees, and transcript link
  • Tables are properly formatted
  • Category _category_.json exists in each directory
  • Document follows the appropriate template structure

Last Updated: January 2026