Getting team documents to look alike and make sense takes two templates and one principle. The principle is fewer but fresh: Google's documentation guide says a small set of fresh, accurate docs beats a large pile in disrepair, and if something exists elsewhere, link to it. The how-to template runs prerequisites, steps, how to confirm it worked, and whom to ask when it fails; in one study, installation instructions rewritten to a template scored better on eight of ten aspects readers rated. Architecture decision records (ADRs) note why a decision was made; when one is reversed, you don't delete it, you mark it superseded and link to the new decision. Research also finds ADRs are often tried and dropped, and that the "considered options" section is the most problematic, often missing or misplaced, so keep the template short and keep that section.
Documentation going out of date is normal, and it throws no errors: eight in ten of GitHub's most popular projects have at some point left references in their docs to code that had been deleted. There are four ways to maintain docs: give every page a responsible role, set verification expiry, change the docs in the same change as the process, and fix pages when they're used. Each one fails in its own way: the owner leaves, expiry notices get treated as spam, the rule exists but nobody follows it, and articles nobody uses never get checked. The deletion principle: delete what's certainly wrong first, and archive what's correct but rarely used. By the end you'll be able to draw up a maintenance table for your team: document type, responsible role, review cycle, and deletion conditions.
Research on rotting team wikis keeps finding three things: gaps and outdated pages are complained about more often than wrong ones; the people who write have no time or have left; and managers want something different from the people who actually write. Not every wiki rots: wikis hold up better when the writers are also the readers, or when the documents solve a clear problem. Diátaxis sorts documents into four kinds (tutorials, how-to guides, reference and explanation), and two questions tell you which kind a document should be, so you can see which kind your team is missing.
Compared with commercial textbooks, open textbooks showed no reliable difference in learning performance across 22 studies combined (g = 0.01), with fewer withdrawals but weaker evidence for that. Among four state-approved math textbooks in California, one scored about 0.05 standard deviations higher than the other three combined. Materials with a minimalist design (mostly rewritten manuals) had a large effect, but the studies are old, the samples small, and the meta-analysis did not go through journal review. The case that one-to-many explanation pays off and Diátaxis's four-way split are both arguments, not data; no study has directly tested re-explaining a course.
There is no 'never comment' school — only 'comment by exception' (Uncle Bob) versus 'comments are part of the design' (Ousterhout, antirez). In their 2024–2025 public debate, both agree on why-comments and against noise comments; the real fights are over interface comments for internal methods, long names as a substitute, and whether comments can be trusted. Controlled studies say quality decides: the same comments moved performance anywhere from -30% to +34% depending on the snippet.
llms.txt is a convention proposed by Jeremy Howard on 2024-09-03 (the spec is now at v2): a Markdown index at your site root written for LLMs. Hand-tested across six frontend docs sites: TanStack, shadcn, Zustand, AI SDK, and Next.js all ship it; React Router is the lone 404. The companion llms-full.txt (full-text version) is live at Anthropic, Cloudflare, and others. This post covers the spec, who uses it, and why it has started to influence library selection.
GitBook is a Git-based documentation platform with Markdown editing, version control, and multi-user collaboration. Ideal for technical docs, API references, and internal knowledge bases. The free plan is sufficient for individuals and small teams.
A breakdown of nine major documentation platforms — their positioning, pros, cons, and ideal use cases. Decision logic: open-source projects → Docusaurus/VitePress, API docs → Mintlify/ReadMe, internal enterprise → Confluence, fastest to launch → GitBook.
After finishing a debug session, just say 'write this up as a post' — Claude Code extracts content from the conversation, applies a template, generates frontmatter, and commits it to the repo. No extra writing required.