Documentation Workflow

The idea is simple: as you build, you document. Not after. Not in a separate sprint. Every commit, every decision, every research rabbit hole gets captured in markdown and published into your app where anyone can read it.

The /docs Folder

Every project gets a /docs folder at the root. This is your working documentation - not polished marketing copy, but real notes from real development.

your-project/
  docs/
    changelog.md
    progress/
      2026-02-03_1400--initial-scaffold.md
      2026-02-03_1900--dark-mode-fixes.md
      2026-02-04_0900--search-implementation.md
      2026-02-04_1500--convex-schema-decision.md
    research/
      auth-options.md
      db-comparison.md
    reviews/
      pr-42-review.md

The key is the docs/progress/ folder. Each session, each decision, each build log gets its own file. A teammate can open the folder and read them one by one, in order, without scrolling through a giant single file.

The Naming Convention

docs/progress/{date}_{time}--{slug}.md

Examples:

• 2026-02-03_1400--initial-scaffold.md
• 2026-02-03_1900--chose-convex-over-supabase.md
• 2026-02-04_0900--refactored-auth-flow.md
• 2026-02-04_1500--code-review-api-routes.md

The date-time prefix keeps them sorted chronologically. The slug tells you what it's about without opening it. Research, decisions, build logs, code reviews - they all go here.

What Goes In /docs

The Rule

If you thought about it for more than 5 minutes, write it down.

Better yet, don't even type it out. Just run /progress or /changelog - the custom commands handle the format, naming, and file creation for you.

Changelog

Keep a running changelog in docs/changelog.md. Format doesn't need to be fancy:

# Changelog

## 2026-02-03

### Added
- Quickstart Kit section with bootstrap prompt and shareable configs
- Custom slash commands documentation (/commit, /handoff)

### Changed
- Navigation updated with new Quickstart Kit section

### Fixed
- Dark mode code block visibility issue

## 2026-02-02

### Added
- Initial site scaffold with 8 documentation sections
- Search functionality with keyboard navigation
- Dark/light mode toggle

Writing Changelog Entries

Just run the command:

/changelog                              # Infer from recent git activity
/changelog added search with filters    # With a specific hint

It reads your recent commits, figures out what category (Added/Changed/Fixed), and appends to the file. If today's date already has a section, it adds to it instead of duplicating.

Progress Logs

Each progress file captures a session, a decision, or a piece of research. One topic per file, with enough context that a teammate reading it cold can follow along.

What a Progress File Looks Like

docs/progress/2026-02-03_1900--chose-convex-over-supabase.md

# Chose Convex over Supabase

**Date:** 2026-02-03
**Type:** Decision

## Context

Needed a backend for the knowledge base site. Requirements: real-time
search, TypeScript end-to-end, minimal setup.

## Options Considered

1. **Supabase** - Postgres-based, good ecosystem, would need additional
   real-time config for live search
2. **Convex** - Built-in real-time subscriptions, TypeScript functions,
   zero config for reactivity

## Decision

Went with Convex. Real-time is built in - no polling, no websocket
setup. Functions are TypeScript which matches the rest of the stack.
Tradeoff: smaller ecosystem than Supabase, but for this use case
the built-in reactivity is worth it.

## Impact

- Added convex/ directory with schema.ts and articles.ts
- ConvexProvider wraps the app in layout.tsx
- Search queries return results in real-time

docs/progress/2026-02-04_0900--refactored-auth-flow.md

# Refactored Auth Flow

**Date:** 2026-02-04
**Type:** Build Log

## What Changed

Moved from custom JWT handling to Convex auth. Removed 3 API routes
and the middleware token check.

## Files Modified

- Deleted: app/api/auth/[...nextauth]/route.ts
- Deleted: middleware.ts
- Modified: convex/schema.ts - added users table
- Modified: app/layout.tsx - swapped auth provider

## Why

The custom auth was 200+ lines of boilerplate doing what Convex auth
does in 20 lines. Less code, fewer bugs, same result.

Writing Progress Logs

Just run the command:

/progress                                   # Infer topic from session
/progress search implementation             # Specify the topic
/progress chose convex over supabase        # Decision log

It generates the filename, picks the type (Build Log, Decision, Research, Code Review), and writes the structured file. Each one is self-contained - a teammate picking it up cold can follow along.

Publishing Docs In-App

The real power move: surface all of this in your application itself. Not hidden in a repo that nobody reads - right there in the app, in a documentation section.

The Pattern

1. Build a docs/changelog route in your app (follow a docusaurus-ish layout - sidebar nav, clean typography, previous/next links)
2. Write markdown files to your /docs folder as you develop
3. Render them in-app using MDX or a markdown renderer
4. Anyone can read them - teammates, clients, your future self

This site (Clodd Work) is itself an example of this pattern. The content lives as MDX files in the app directory, rendered with @next/mdx, navigated with a sidebar.

Minimum Viable Docs Section

At minimum, your app should surface:

• Changelog - What changed and when
• Progress logs - The individual session/decision files, listed chronologically

Stretch goals:

• Architecture overview - System design at a glance
• API reference - Auto-generated or manually maintained
• Search across all docs - Full-text search over progress logs

Why Individual Files Work Better

• A teammate can read them one by one - each file is a self-contained story
• Git blame is useful - you see who wrote what and when
• No merge conflicts - two people can write progress logs at the same time
• Easy to reference - link to a specific decision from a PR or commit message
• Natural chronological sort - the date prefix does the work

Making It a Habit

The trick is to make documentation a side effect of development, not a separate task. The slash commands make it frictionless:

1. Build something - Work normally
2. /commit - Commit the work
3. /changelog - Update the changelog (one command)
4. /progress - Write the session log (one command)
5. /handoff - When context fills up, save state and start fresh

Four commands that keep your project documented as you go. Claude does the writing. You just type the slash.