This is the closest comparison there is, because a Wiki Pilot wiki is a folder of markdown in your repository. If you believe docs belong in the repo, versioned with the code and reviewed in PRs — so does Wiki Pilot. It’s the difference between that belief and what a plain docs/ folder actually delivers over time.
Most docs/ folders follow the same arc. Created with good intentions. Three files by the end of the quarter: a setup guide that mentions a Node version two majors back, an architecture sketch from before the rewrite, and notes.md, author unknown. Nobody can say which parts are still true, so new engineers learn to skip the folder and ask in Slack.
Wiki Pilot addresses the three reasons that happens.
The blank page, the missing site, the silent rot
Nothing starts a plain folder. The first page costs the most, and it costs a senior engineer an afternoon. wikipilot init scans the repo and drafts the wiki before anyone writes a word — an overview, an onboarding tour, pages for how the core flows work and why each major dependency is there. Real prose drafted from real code, marked where a human should verify. Editing beats authoring, so the docs actually get written.
A folder is not a site. Markdown on GitHub is readable, but nobody browses it. wikipilot build renders the folder into a static site with navigation, full-text search, dark mode, and diagrams — plain HTML, CSS, and JS, no server. Publish it on GitHub Pages, any file host, or a hosted wikipilot.dev subdomain. The difference between “we have docs somewhere in the repo” and “go to the wiki” is whether people use them at all.
A folder can’t tell you it’s wrong. This is the part no convention fixes. Every Wiki Pilot page carries a contract in its frontmatter:
sources:
- src/billing/**
last_synced: "d70bf9ba"
The page names the files it documents and the commit the prose was verified against. When the sources move on, the built page shows a “may be outdated” banner until someone re-verifies it. The repo also gets a bundled Claude Code skill (update-wiki), so “audit the wiki” is a sentence you say to your coding agent, not a chore you schedule.
The short version
| Wiki Pilot | Plain docs/ folder | |
|---|---|---|
| Format | Markdown in your repo | Markdown in your repo |
| First draft | Drafted from the code by init | Blank |
| Reading experience | Static site: nav, search, diagrams | Files on GitHub |
| Staleness | Per-page contract, visible banner | Unknowable |
| Keeping it current | update-wiki skill audits against sources |
Memory and goodwill |
| Lock-in | None — delete the tool, keep the markdown | None |
When the folder is enough
A small library with a thorough README doesn’t need a wiki, and a two-person project can keep its docs true by talking to each other. The folder stops being enough at roughly the moment someone reads a page, hesitates, and goes to ask whether it’s still accurate. That question — “is this still true?” — is the one a plain folder can never answer and the one Wiki Pilot was built to.
And since the output is ordinary markdown, trying it is reversible: run init on a branch, look at what it drafts, and if you don’t keep the tool you still keep the files.