Docs Are Your Product's Second Face: Developer Documentation for Vibe Projects

Let's draw the boundaries first, so you don't read the wrong piece. This guide is not about traffic: search engines and AI discovery tactics live in vibe-project-seo-aeo-guide (the SEO/AEO playbook) — that's "how to get found"; this piece is "what keeps people after they're found." It's also not about the manual you write for agents: agents-md-project-manual-guide covers AGENTS.md — the project manual written for coding agents; and it's not about requirements documents: for PRD writing, see writing-prd-for-ai-agents. This guide covers exactly one thing: how to write developer documentation for humans — from Quickstart to API reference, from docs-as-code discipline to an honest assessment of whether llms.txt is worth your afternoon.

1. Documentation Decides Conversion: It's Your Product's Second Face

A developer discovering a new tool follows an almost fixed path: glance at the landing page → click into the docs → decide whether to try it. Most vibe projects die at step two. Not because the product is bad, but because the docs homepage fails to answer three questions within 30 seconds: what does this do, can I get it running in three minutes, and who do I ask when something breaks?

Big companies can paper over bad docs with brand and sales. A one-person team has no such luxury. Your docs are your salesperson, your support rep, and your evangelist, working 7×24 without sleep. Treating documentation as "something you slap together after the code is done" means handing the most critical link in your acquisition funnel over to luck.

Think of it another way: vibe coding made writing code cheap, so code is no longer the scarce resource. When anyone can ship a working demo overnight, the scarce resource becomes trust — and documentation is the cheapest way to build it. A project with a crisp Quickstart naturally signals "the author is reliable, the code probably isn't a mess either." Conversely, docs full of 404s and stale screenshots lead users to one inference: the code is equally unmaintained.

So this guide's stance is explicit: documentation is not a cost center; it's step two of your conversion funnel, right after the landing page. Spend your budget (your time) in that priority order.

Three flavors of bad docs are everywhere in vibe projects — check which one is yours:

• "Autobiography" docs: the homepage rambles about why the author built this, the emotional journey, the agonizing over tech choices. Readers don't care about your journey; they care whether their problem gets solved. Move the autobiography to your blog; keep only "what this is, how to run it" on the docs homepage.
• "Archaeology" docs: the Quickstart commands are three months old, parameter names changed since; screenshots show the v0.3 UI while the product is at v1.2. As noted above, this flavor is uniquely destructive: it wastes 30 minutes of the reader's time, then earns you a verdict of "unreliable author." The root cause is always the same — docs living outside the repo (see section 5).
• "Manual" docs: every config flag and parameter laid out flat, no scenarios, no ordering, no "you usually only need these three." The problem isn't too little information; it's unorganized information. Readers want to be walked through; they don't want a dictionary.

All three share one trait: they're written from the author's perspective. The test is always the reader's perspective: can a stranger who's never met you get the thing running?

2. Write the Quickstart First: Inverted Pyramid and the Five-Minute Test

The biggest mistake in docs writing is organizing by "the author's logic": background first, then architecture, then how to use it. Readers arrive with "their own questions" — and they care about exactly one thing: can I get this running fast and see whether it's what I need.

So docs should follow the inverted pyramid: the most important thing goes first. The first screen of the homepage should be three install commands plus a screenshot (or terminal output) of it working. Background, design philosophy, architecture diagrams — important, but they belong to the "after the reader has decided to adopt it" phase. Push them all down.

The acceptance test for a Quickstart is singular and brutal: find someone who's never seen your project and get them to a working Hello World within 5 minutes. If you can't, rewrite. Don't hide behind "my project is complex" — complexity is precisely why you need a better Quickstart. Why is Stripe's documentation copied across the industry? Because its Quickstart genuinely gets you to your first test payment in minutes.

A passing Quickstart has three hard requirements:

• Prerequisites pinned to versions. "Requires Node.js" fails; "Requires Node.js 20+ (22 LTS recommended)" passes. The most common Quickstart failure in vibe projects is environment assumptions: the author's machine runs Python 3.12, the reader has 3.9, the pasted commands blow up, and the reader leaves.
• Commands that run on copy-paste. Every command must be complete and copyable — no half-baked "replace <your-key> with your key" without at least a working sample value, clearly marked where to substitute. No implicit steps between commands ("cd into the project directory first" will hard-block a beginner if omitted).
• Show what success looks like. After running the commands, what should the terminal print? What page should the browser open? Paste the expected output. When readers can't match the output, they can't tell whether they or the docs are wrong — and they'll most likely blame you.

Anti-pattern: leading with the architecture diagram. Many technical authors can't resist showcasing their elegant system design — six microservices drawn beautifully. But a first-time visitor doesn't even know what problem this solves yet; the diagram is pure noise to them. Remember the order: get them running first, then help them understand; give the fish before teaching to fish.

One before/after rewrite shows the difference:

Before (author's perspective): "This project is a plugin-architected Markdown notes app supporting multiple storage backends. Before starting, please make sure you understand our design philosophy (link: design philosophy) and choose the right installation method for your OS…" — three paragraphs in, not a single command in sight.

After (reader's perspective):

# 1. Install (requires Node.js 20+)
npm install -g moonote

# 2. Start (browser opens http://localhost:3000)
moonote start

# Seeing "Moonote running at http://localhost:3000" means success.
# First time here? Walk through the 5-minute tutorial: [link]

Three commands, one line of "what success looks like," one tutorial entry point. Design philosophy, plugin architecture, storage backends — all of that comes after the reader is up, running, and interested. Every line of a Quickstart should answer "what does the reader do now," not "what does the author want to say."

3. The Divio Four Quadrants: Mixed Genres Are the Root of Docs Chaos

Quickstart done — the next big trap: docs keep growing and getting messier. The root cause is usually not writing too little, but mixing four genres together. Divio's documentation system (documentation.divio.com) divides docs into four quadrants along two axes: oriented toward study vs. work, theoretical vs. practical:

Figure: the Divio documentation quadrants. Horizontal axis: "studying vs. working"; vertical axis: "theory vs. practice."

• Tutorials (study × practice): walk the reader through completing something by hand; what they learn is "how to do this kind of thing." The voice is "follow along with me." Example: "Follow this tutorial to build your first xxx app." Tutorials are allowed to be verbose, because the goal is learning.
• How-to guides (work × practice): solve one concrete problem, assuming the reader already knows what they want. The voice is "to do X, follow these steps." Example: "How to enable auth for the API." Guides should be short and direct — no explaining the theory.
• Reference (work × theory): describe "what things are," for lookup. API endpoint tables, config option lists, error code tables all live here. Reference docs are stable and predictable in structure — readers come to "look something up," not to "read."
• Explanation (study × theory): answer "why." Why the architecture is designed this way, what problem an abstraction solves. Explanatory docs build deep trust, but only for readers who are already onboard.

Classic symptoms of mixing: explaining theory inside a tutorial (the reader just wants it running; you're lecturing on design philosophy), writing tutorials inside reference docs (five paragraphs of "best practices" stuffed into a parameter table), opening a how-to with a from-scratch primer ("How to configure HTTPS" starting with three pages of TLS history). Every mix adds cognitive load on the reader.

Practical advice: give each genre a fixed home, e.g. /tutorials, /how-to, /reference, /concepts. Before writing a new doc, ask: what question is the reader bringing? "I want to learn" → tutorial; "I want to solve X" → how-to; "I want to look up the definition of Y" → reference; "I want to know why" → explanation. If you can't tell, the doc is trying to do two things — split it in two.

4. Writing API Reference: Let Machines Generate It, Humans Only Write the Story

API reference is where vibe project docs most often look diligent yet prove unusable. An author spends two weeks hand-writing Chinese descriptions for every endpoint, and the parameter names don't match the code — because hand-written things always go stale. Rule number one of API reference: generate whatever can be generated; never hand-write it.

If you define your interfaces with OpenAPI/Swagger, the reference pages should be generated from the spec (Redoc, Scalar, and Stoplight Elements all work out of the box). Code changes → spec changes → docs change. As long as that chain holds, the reference pages are always correct. Human effort belongs where machines can't reach: how-to guides and conceptual explanations — "when to use this endpoint" and "the trade-offs behind this design."

Generated or hand-written, every endpoint needs three things:

• One copyable curl example. Don't just give the parameter table; give a request that actually runs. A developer evaluates an API by: copy curl → run → inspect the response. The shorter that loop, the higher the conversion. Spell out the auth header and Content-Type in the example — don't make readers guess.
• An error code table that says "how to fix it." "400 Bad Request" as a description is the same as writing nothing. Write it as: 400 (missing required field email) → check the request body; 401 (token expired) → re-run /auth/refresh; 429 (rate limited) → read the Retry-After response header. An error table's value isn't in "listing" but in "giving the next step."
• Version annotations. Mark every endpoint with the version it became available in and the version it was deprecated in. Vibe projects iterate fast; deprecating without annotation is planting mines for your future self. Deprecated endpoints need a migration path — "deprecated" alone isn't enough.

A rough test for whether your API docs pass: turn off your memory, read only the docs — can you drive the core flow without reading the source? If even the author can't, don't expect strangers to.

5. Docs-as-Code: The Discipline of Keeping Docs in the Repo

Docs' worst enemy isn't bad writing — it's staleness. Stale docs damage trust more than no docs: with no docs, readers know to ask; stale docs send readers down a wrong path for half an hour, then kill their trust in your project completely.

Docs-as-code boils down to three disciplines, all perfectly copyable by vibe projects:

• Docs live in the repo. Markdown files sit in the same repository, docs/ next to src/. The payoff is natural version sync: check out the v2.1 tag, see the v2.1 docs. Docs kept in a third-party wiki or Notion will drift from the code within three months — because the person changing the code won't remember to update docs in another system.
• Doc changes go through PRs, reviewed together with code. A feature PR must include doc updates, or it doesn't merge. This feels heavy at first, but it's the only mechanism that keeps "code and docs living and dying together" over the long run. The review bar for docs is simple: can you run the feature by following the docs?
• CI checks for dead links. Run a link checker like lychee across the whole site in CI; dead links turn the build red. The most common rot in vibe project docs is links pointing at old versions and old repo names — machines check those far more reliably than humans.

Google's Developer Documentation Style Guide (developers.google.com/style) is worth reading through — not because it's authoritative, but because it decomposes "how to write clearly" into executable rules: active voice, second person for steps, one action per step, command first then explanation. Vibe authors don't need to memorize it; one line suffices: docs are an operator's manual written for others, not study notes written for yourself — study notes can stream; operator's manuals can't.

6. Docs for Agents: An Honest Assessment of llms.txt

In September 2024, Jeremy Howard proposed a community convention at llmstxt.org: llms.txt. The idea is simple: put a /llms.txt file at the site root, in Markdown, listing the site's most important pages with one-line summaries each, plus a /llms-full.txt with the full content. When an agent crawls, it reads structured Markdown instead of swimming through HTML soup.

Adoption did follow. Simon Willison ran docs-for-llms experiments and wrote an llm-docs plugin; in 2026 he documented a case where Claude actually read a site's llms.txt and generated working doc links from it. In other words, in at least some agent workflows, this file genuinely gets read.

But three honest caveats come first:

• It's a community proposal, not a formal standard. No RFC, no W3C blessing — just a convention some people adopted. Don't plan around it as if it carried the same weight as robots.txt.
• Google has stated it doesn't use it for search. It's neither a ranking signal nor a crawler directive. If you hoped llms.txt would boost SEO, abandon that hope.
• Real-world read frequency is tiny. prosopo.io published 12 days of access logs in October 2026: robots.txt was requested 511 times; llms.txt, 3 times. The agent ecosystem is early; the agents that read this file are a small minority.

The verdict: worth doing, but not as a traffic channel. The cost is one afternoon: write a Markdown file listing your Quickstart, core concept pages, and API reference entries, one summary sentence each; then generate an llms-full.txt concatenating the important pages. Treat it as "a friendly gesture toward future agents," not "an acquisition lever." With the right mindset it's worth doing; with the wrong one (expecting traffic), you'll be disappointed.

Hands-on tips for writing llms.txt: list only the 10–20 most important pages — don't dump the whole sitemap in (that's llms-full.txt's job); each entry gets one sentence on "what problem this page solves," no marketing copy; update it on every release — same discipline as docs-as-code.

A minimal working llms.txt looks like this — adapt freely:

# Moonote

> Markdown notes app you learn in 5 minutes. Local-first, plugin-friendly.

## Quickstart
- [Install & first launch](https://moonote.dev/quickstart): three commands to running, with expected output
- [5-minute tutorial](https://moonote.dev/tutorials/first-note): create your first note

## Core concepts
- [Plugin architecture](https://moonote.dev/concepts/plugins): why plugins only get a restricted API

## API reference
- [REST API overview](https://moonote.dev/reference/api): endpoints, auth, error code table

## Full docs
- Everything concatenated: https://moonote.dev/llms-full.txt (single file, ~80KB)

Three things to note: the title line uses # with the product name; the > blockquote states in one sentence what the product does (agents use it to decide whether to keep reading); each link says "what problem it solves" rather than parroting the page title. And llms-full.txt is just those pages concatenated into one Markdown file, convenient for feeding an agent's context window in one shot.

7. Navigation Is Documentation: Don't Let Readers Get Lost in Your Docs

Content done — half the work remains in navigation. The most common navigation disaster in vibe project docs: a single sidebar ordered by the author's writing sequence. New readers read top-down, discover by article three that it has nothing to do with them — and close the tab.

Sidebars should follow the reader's journey, not the writing order. A practical grouping: "Get started" (Quickstart + install + first tutorial) → "Solve concrete problems" (how-tos, grouped by task) → "Look things up" (API reference + config) → "Understand the design" (explanations). That maps exactly onto Divio's four quadrants — information architecture and methodology are the same thing.

Three more navigation details, all cheap with visible payoff:

• On-site search is a requirement, not a bonus. Past ~20 pages, readers stop using the sidebar to find things. Algolia DocSearch is free for open source and takes an afternoon to wire up. A docs site without search is a book without an index.
• A version switcher. When v1 and v2 APIs differ, readers must switch doc versions in one click. Docs-in-repo gives you versioning for free, but the frontend needs a visible switcher — otherwise readers never know whether they're reading the current version.
• Every page ends with "Was this helpful?" or "Spotted an error? Open a PR." The shorter the docs feedback loop, the slower the rot. The "twice-asked goes into the FAQ" rule from the next section depends on exactly this loop.

Good navigation makes readers feel your docs are "easy to find things in"; bad navigation means the best content might as well not exist.

8. Measuring Docs: How Do You Know They're Good?

The hardest part of docs is the lack of feedback — code has tests, docs don't. So install three "dashboards" proactively; none needs fancy tooling:

• Read the search terms. Your docs site's internal search log is the most honest user research you'll get: if lots of people search "auth failed," the auth section is unclear or buried. Spend 20 minutes a month on the top-20 search terms; whatever ranks high is a hole in your docs.
• Label doc-driven issues. In GitHub issues, tag anything caused by "docs unclear/wrong" with a docs label. Count quarterly: if the docs-labeled share is climbing, your docs are rotting; if one page keeps getting asked about, rewrite that page. This is the quantified version of "twice-asked goes into the FAQ."
• Spot-check Quickstart completion. Quarterly, find someone who's never used your project (a friend, a community member), watch them run the Quickstart from zero, and note where they get stuck. Authors can never test their own Quickstart — they know all the implicit steps. It's the cheapest usability test there is; twice a year is plenty.

None of these requires you to become a data analyst. They serve one purpose: turning "are the docs good" from a feeling into evidence, so you know what to fix in the next revision.

9. Docs i18n: When Is an English Version Worth It?

Once a vibe project gets featured on Product Hunt, Hacker News, or X, English-speaking readers show up. Whether to do English docs depends on your acquisition channels: if over ~30% of traffic comes from the English-speaking world, English docs aren't optional. Check your analytics; don't go by gut feel.

The practical i18n ladder has three rungs, ordered by investment:

• Rung 1: bilingual Quickstart. Translate only the Quickstart and install pages; leave the rest in Chinese. Best ROI per unit of effort — English readers can get running, then machine-translate the deeper Chinese docs. Many indie projects stay on this rung for years, and it's plenty.
• Rung 2: bilingual core paths. Quickstart + common how-tos + API reference (API reference is mostly English anyway, so it's cheap to translate). Tutorials and explanations can wait.
• Rung 3: fully bilingual site. Only when you're explicitly targeting overseas markets and have the stamina to maintain it. The biggest trap of full bilingualism isn't translation — it's sync: Chinese gets updated, English doesn't, and bilingual becomes double the stale docs.

On translation quality, machine translation plus human review is the realistic choice for vibe teams. One red line: never translate code samples, commands, or parameter names. Translate only the prose. Docs that render moonote start in Chinese are a joke — but that joke genuinely exists in the wild.

For directory structure, split by language (/docs/zh/..., /docs/en/...) rather than mixing both languages in one file. Mixed files are a maintenance nightmare, and PR reviewers can't tell which language changed.

10. Maintenance Cadence, and the Launch Checklist

Finishing docs isn't the end — it's the start of maintenance. The most common death curve for vibe projects: shiny docs at launch, docs and code telling different stories three releases later. Preventing rot needs no elaborate process, just two rhythms:

• Update docs with every release. Add one item to the release checklist: "Do the docs reflect this release's changes?" A feature without docs is an unreleased feature; a deprecation without annotation is a planted mine.
• Let user feedback drive iteration. One iron rule: any question asked twice belongs in the FAQ. Recurring questions in issues, chats, and emails mark holes in your docs. Turn answers into docs and link them next time — the highest-ROI maintenance move there is.

Finally, the pre-launch docs checklist — check each item off:

1. A stranger gets through the Quickstart in 5 minutes (actually tested on someone — not by you)
2. The homepage's first screen shows install commands and a working screenshot, no architecture diagram in the way
3. Tutorials / how-tos / reference / explanations each in their place, no genre mixing
4. Every API endpoint has a copyable curl example
5. The error table explains "how to fix," not just "what it is"
6. Version annotations are complete; deprecated endpoints have migration paths
7. Docs live in the code repo; feature PRs include doc updates
8. CI runs dead-link checks, all green
9. llms.txt sits at the site root, listing only core pages (optional but recommended — one afternoon)
10. The FAQ covers questions asked twice or more

Good docs won't resurrect a bad product; but bad docs will absolutely starve a good product of users. For vibe projects, documentation is your cheapest growth lever — don't wait until users are churning to start writing.