Skip to content

Documentation Conventions

Repository Structure

9-Section Organization

This knowledge base uses a 9-section structure optimized for solo founder execution:

  1. 00-Command-Center - Daily operations hub (update daily)
  2. 01-Product - Product definition (update monthly)
  3. 02-Market-Competitive - Market analysis (update quarterly)
  4. 03-Branding-Creative - Brand identity (update annually)
  5. 04-Marketing-Growth - GTM execution (update weekly during launch)
  6. 05-Beta-Partnerships - Testing & partnerships (update weekly)
  7. 06-Team-Hiring - Organizational design (update quarterly)
  8. 07-Fundraising - Investor relations (update bi-weekly)
  9. 08-Operations - Technical/legal operations (update monthly)
  10. 09-Research - Technical explorations (update as needed)

Frontmatter Standard

Required Fields (6)

Every markdown document must have these frontmatter fields:

---
title: <Human-readable title>
summary: <1-2 line description>
owner: founder
status: draft|active|archived
audience: [internal, investor, developer, enterprise, partner]
last_updated: YYYY-MM-DD
---

Field Definitions

title: Human-readable title (appears in navigation) summary: Brief description (1-2 lines max) owner: Who owns this document (currently "founder" for all) status: - draft = In progress, incomplete - active = Current and complete - archived = Superseded but kept for reference

audience: Who can see this (pick 1-3 max) - internal = Founder only - investor = For investor sharing - developer = For developer audience - enterprise = For enterprise buyers - partner = For partner sharing

last_updated: YYYY-MM-DD format, update when modifying content

Optional Fields

Use only if needed:

tags: [product, gtm, funding]  # For cross-references
priority: high|medium|low      # For Command Center sorting

Update Cadence

Default Cadences (per task.md)

  • 00: Daily
  • 01: Monthly (first Monday)
  • 02: Quarterly (Jan/Apr/Jul/Oct)
  • 03: Annual (unless pivoting)
  • 04: Weekly during launch, monthly otherwise
  • 05: Weekly (pipeline moves fast)
  • 06: Quarterly (or when hiring)
  • 07: Bi-weekly (market changes)
  • 08: Monthly (first Monday)
  • 09: As needed

How to Update

  1. Open the document
  2. Update last_updated field in frontmatter
  3. Change status if appropriate (draft → active)
  4. Add brief update note at top if significant changes

Document Creation

New Document Checklist

  1. Place in appropriate section directory
  2. Follow filename convention: lowercase-with-hyphens.md
  3. Add all 6 required frontmatter fields
  4. Create section README if new subdirectory
  5. Update parent navigation if needed

Section README Template

Every section has README.md with:

# Section Name

## Purpose: What this section covers
## Update Cadence: How often to review/update
## Key Files:
- file.md (purpose)
- file.md (purpose)

Cross-References

  • Use relative paths: ../02-market-competitive/competitive-landscape.md
  • Descriptive link text: Competitive Landscape
  • Keep links up to date when moving files

Root README.md maintains "Quick Access Links" section with most critical files. Keep this current.

Content Guidelines

Writing Style

  • Brevity over completeness: Prefer focused, actionable docs over comprehensive reference
  • Update-friendly: Structure to make updates easy (templates, checklists)
  • Audience-aware: Each document has clear target audience

File Organization

  • Logical grouping: Files that are updated together should be near each other
  • Avoid deep nesting: Keep directory structure flat (max 2 levels deep)
  • Use README files: Each subdirectory needs README for navigation

Legacy Content

docs-legacy/

Old 17-section structure archived here. Don't delete - provides rollback capability and reference.

Migration Tracking

  • Progress tracked in task.md
  • Detailed mappings in migration-map.md (archived after Phase 4)

Quality Checks

Before Committing Changes

  • [ ] All frontmatter fields present and current
  • [ ] last_updated updated if content changed
  • [ ] Links work (test navigation from root)
  • [ ] No broken internal references
  • [ ] Update cadence maintained

Validation Script

Run scripts/validate-docs.sh to check: - Frontmatter completeness - Link integrity - Stale content detection - Duplicate detection

Common Patterns

Update Checklist Usage

Each section has update-checklist.md - use before updating: - Review cadence guidelines - Check related sections - Follow update template if in hurry - Document key metrics

Status Field Usage

Use consistently: - draft: Working on it, not ready for sharing - active: Complete, current, shareable with appropriate audience - archived: Superseded but keeping for reference/history

Time Stamping

Always use YYYY-MM-DD format for dates: - last_updated: 2025-11-06 ✓ - last_updated: 2025-11-6 ✗ (missing leading zero) - last_updated: Nov 6, 2025 ✗ (wrong format)

Troubleshooting

Can't Find a Document?

  1. Start at root README.md
  2. Check appropriate section README
  3. Use file search (Ctrl/Cmd+P in editor)
  4. Check docs-legacy if looking for old content
  1. Check file path (relative vs absolute)
  2. Verify file exists in expected location
  3. Update link or move file
  4. Test navigation from root

Stale Content?

  1. Check update-checklist.md in section
  2. Review update cadence
  3. Update last_updated if content still relevant
  4. Consider archiving if superseded

Quick Reference

Need to update? → Check section's update-checklist.md Want to share with investors? → Ensure audience includes investor Can't find something? → Start at root README, use Quick Access Links Is this still current? → Check last_updated in frontmatter What cadence? → See this document or section README

  • Task tracking: task.md - Restructuring progress
  • Section overviews: Each section's README.md
  • Update checklists: Each section's update-checklist.md
  • Validation: scripts/validate-docs.sh

Last Updated: 2025-11-06 Owner: founder Audience: [internal]