Document Site Driven Development: Shipping Docs Before Code

What is Document Site Driven Development?

In software development, documentation is almost always an afterthought. But in the age of AI-assisted development, flipping this order brings significant advantages.

Document Site Driven Development follows this cycle:

Write what you want to build as documentation first
AI agents read the documentation and understand the task
Implement code based on the documented specifications
Update documentation with implementation details

The key distinction: not a README or a wiki, but a documentation site. Structured information that is readable by both humans and AI agents.

Why Fumadocs?

Fumadocs is a documentation framework built on Next.js. Here’s why it fits this workflow perfectly.

Separation of Content and Structure

Fumadocs manages content through MDX files while defining sidebar navigation via meta.json. This separation lets you focus on writing content without worrying about site structure, and restructuring is trivial.

Natural Fit for Monorepos

Placing the documentation site at apps/docs within a monorepo feels natural. Product code and documentation live in the same repository, so PRs can include both code and doc changes for unified review.

repo-root/
├── apps/
│   ├── docs/          # Fumadocs
│   │   ├── content/
│   │   │   ├── en/
│   │   │   └── ja/
│   │   └── ...
│   └── web/
├── packages/
├── AGENTS.md
└── ...

Built-in i18n

Fumadocs supports internationalization out of the box. The entire project — code, comments, commit messages — stays in English, while the documentation site serves content in both English and Japanese.

This means humans can read specifications in their native language. Design decisions, architecture rationale, nuanced trade-offs — these are easier to absorb in your first language.

Integration with AGENTS.md

The real power of this approach emerges when working with AI agents.

In the repository root AGENTS.md, include a directive like this:

## Understanding Tasks
 
Refer to the documentation in `apps/docs` for features to implement
and their context. Follow the specifications documented there.

With this setup, AI agents treat documentation as specifications, autonomously understanding what needs to be built. You no longer need to explain every task detail manually.

Documentation Becomes the Spec

Traditional documentation explains what was built. In Document Site Driven Development, documentation prescribes what to build.

Traditional Approach	Document Site Driven Development
Write code → Write docs	Write docs → Write code
Docs trail implementation	Docs guide implementation
Docs are for humans	Docs are for humans and AI
Docs go stale quickly	Docs stay current (written first)

Lessons from Practice

Several insights emerged from running this approach in production.

1. If You Can’t Write the Doc, the Design Isn’t Ready

When you sit down to write documentation and get stuck, it’s a signal that the design isn’t clear yet. Writing docs becomes a forcing function for clear thinking.

2. “Docs for AI” and “Docs for Humans” Have Different Purposes

API references and mechanical specifications serve as direct context for AI agents during implementation. Architecture guides and design rationale, on the other hand, are read by humans during reviews and decision-making. These two types differ in audience and purpose, so organizing them into separate directories or categories is recommended.

3. Doc Review = Design Review

Reviewing documentation changes in a PR is effectively a design review. By reviewing docs before code, you catch misalignment before implementation begins.

4. Day 1 Matters

“We’ll add docs once the code stabilizes” means docs never get added. Set up Fumadocs the moment you create the repository. Include it in your first commit.

The Workflow

Here’s the workflow described above as a concrete end-to-end example.

Step 1: Write the Documentation

Before any code, document the planned feature or refactor. For example, create a page at apps/docs/content/en/architecture/notification.mdx:

# Notification System
 
## Overview
Provide in-app and email notifications when specific events occur.
 
## Requirements
- Support multiple channels: in-app, email, Slack
- Users can configure preferences per channel
- Retry failed deliveries with exponential backoff
 
## Architecture
- Event bus: `packages/events`
- Channel adapters: `packages/notifications/channels/`
- Preference store: per-user settings in database

Step 2: Commit the Documentation

Commit the docs first. No code has been written at this point.

Step 3: Let AI Agents Execute

AI agents follow the AGENTS.md directive, read the documentation in apps/docs, and begin implementation.

Step 4: Update Documentation Post-Implementation

Reflect any details or changes discovered during implementation back into the documentation.

Summary

Document Site Driven Development addresses multiple problems simultaneously:

Documentation staleness: Writing first keeps docs current
AI agent context: Structured docs serve as machine-readable specifications
Design ambiguity: If you can’t document it, you haven’t designed it
Multilingual support: Fumadocs i18n keeps code in English, docs in your native language

Fumadocs is an excellent framework for this purpose. Set it up from day 1 of your monorepo, and start building docs before code.

That’s all from the field, where we write docs before code.