标签：#documentation

The most common documentation failure is not a weak prompt or a lazy writer; it is the absence of a clear boundary between machine-draftable content and human-owned claims. A pipeline that drafts reference sections with free-tier model access and then verifies them with a symbol drift check turns docs into a testable artifact instead of a trust exercise. The model writes the inventory, and the human owns the promises. Why documentation rots inside a healthy CI pipeline Documentation bugs share a distinctive property: they are usually discovered by the people who consume the API, not by the pipeline that builds it. A function renamed in the last refactor stays documented under its old name until a user files an issue, and a newly added flag never appears in the docs at all. The root cause is structural, because nothing in the merge pipeline compares the documented surface against the actual code surface. A prompt cannot know what changed inside a pull request, so the fix has to live in the pipeline around the model. The workflow drafts reference material, validates that every documented symbol still exists, and routes the remaining claims to a human reviewer. That division of labor is the entire design, and each step has a concrete tool. The ownership boundary: what a model may draft The first step is to separate documentation into two classes by asking a single question: can this statement be verified against the codebase alone? If the answer is yes, a model may draft it, and if the answer is no, a human must own it. The table below applies that test to the statement types that appear in most API docs. The model may draft A human must own Function and class inventories Behavioral guarantees CLI flags and their defaults Security and authentication properties Config keys and their types Compatibility and support promises Error codes and exit statuses Deprecation timelines Compilable usage examples Performance or cost claims Parameter descriptions from signatures Ratio

In release 4.0, the Ruby Powers-That-Be have brought class Pathname into the Ruby core. This is a Very Good Thing. Through its many instance methods, a Pathname object provides a consistent and convenient interface to numerous methods in other classes and modules: Wraps almost all methods in class File and module FileTest . Wraps some methods in class Dir and module FileUtils . Advantages of using Pathname instead of these others: You don’t have to know which class or module has which methods. You don’t have to keep typing the class name and path variable. However, for many of the Pathname methods, the existing documentation merely links to another method in another class, with scant or no local examples. That documentation may be seen in Ruby 4.0 . I've completed a re-write of the documentation (with the usual excellent reviewing by Peter Zhu). It may be seen for now in Ruby master , and which will be release with Ruby 4.1 later this year. The re-write gives a Pathname -local description and example for each method. (No more linking to a similar or underlying method elsewhere.) I've also revised the documentation for the class itself, and added a "What's Here" section. Happy Pathnames!

Every developer has been there: you clone a promising repository, and the README is either missing, three years stale, or says "docs coming soon." Even when documentation exists, you still have to wade through thousands of lines of code to understand the architecture, entry points, and dependencies. grow-hack is an open-source project that aims to eliminate that pain. Paste a public GitHub URL, wait about sixty seconds, and receive a complete, professional documentation package — Markdown and styled PDF — generated by an LLM that actually reads the code, not just the README. This is the first module of a larger content creation platform. The core idea is that once a repository is parsed and analyzed, the resulting RepositoryKnowledge object becomes a reusable asset for future modules: blog posts, LinkedIn articles, X threads, tutorials, and presentations. In this teardown, we'll look at how grow-hack works, the smart engineering choices it makes, and why it's more than just a documentation generator. The Pipeline: From URL to PDF The application is a Flask web app that orchestrates a LangGraph-based agent pipeline. The flow is straightforward: Flask UI -> LangGraph workflow -> GitHub fetch -> Parser -> Analyzer -> Knowledge object -> Documentation generator -> Reviewer -> Markdown/PDF Each stage is handled by a dedicated agent: GitHub Agent ( agents/github_agent.py ): Validates the URL, fetches metadata via the GitHub REST API (using PyGithub), and clones the repository with GitPython. Parser ( services/parser.py ): The workhorse. It walks the repository tree, ignoring generated directories and binary files, and extracts README, configuration files, dependencies, and source code structure. It infers the language, framework, package manager, entry points, and overall architecture. Analysis Agent ( agents/analysis_agent.py ): Takes the parsed data and, with the help of an LLM, produces a structured RepositoryKnowledge object. Documentation Agent ( agents/documentation

Disclosure: I build Schemity , a desktop ERD tool - this post is from our blog and uses it for the examples. TL;DR: The database has a built-in place to document a column - COMMENT ON COLUMN in PostgreSQL, the COMMENT attribute in MySQL - and almost nobody fills it in, because a sentence of prose has to travel the same path as a schema change: a migration file, a review, a deploy. Schemity keeps field descriptions in the diagram instead, where editing one generates no SQL, reads existing database comments in on import, and exports the result as a data dictionary. You can document a database column without touching the database: write the description in the model rather than in the schema. That sounds like a dodge until you price the alternative. The database's own mechanism for column documentation, COMMENT ON COLUMN in PostgreSQL and the COMMENT attribute in MySQL, sends a sentence of prose down exactly the same path as a change to how data is stored - a migration file, a code review, an approval, a deploy window - and on MySQL it does something worse than that. Schemity keeps field descriptions in the diagram, where editing one produces no SQL at all. This is why so many production schemas have thousands of columns and almost no comments. Not because nobody wanted to write them. Because writing one costs a deploy. How do I document a database column without running a migration? Keep the description in the model rather than in the storage engine. A field description is a fact about what the column means to your team; it changes no type, no constraint, no index, and nothing about what the database will accept. When it lives in the diagram, editing it is like editing a comment in a code file: you change it, review it in the same pull request as everything else, and nothing has to run against production for it to take effect. The moment that description is a column comment, it stops being prose and becomes DDL. Now it needs a migration file, and the migration needs a

Originally published on hexisteme notes . I keep my operating judgment in small, versioned files — one file per decision, each with a status, a list of what it supersedes, and a change history. It's a lightweight way to stop re-litigating the same argument every few weeks: write the judgment down once, and the next time the situation comes up, read the file instead of re-deriving the answer from scratch. Most of the time this works exactly as intended — a rule gets written, a rule gets proven wrong, a newer rule replaces it, done. This is the story of the one time that didn't happen, and why "didn't happen" doesn't look like an error. It looks like a rule sitting there, marked active, doing precisely what it was told to do. The gate One of my rules governed how to use a panel of eight simulated reviewers I sometimes convene for open-ended judgment calls — different personas critiquing the same plan from different angles. The panel's response includes, among other things, an "internal consistency" score: roughly, how much the eight answers agree with each other. Early on I wrote a gate around that number: if internal consistency comes back under 70%, don't adopt the panel's conclusion on its own. Low agreement, the reasoning went, meant the panel hadn't converged on anything trustworthy. The supersession, with receipts The gate lasted exactly as long as it took to hit a counterexample. I ran the panel on an architecture question and got back a response at 21% internal consistency — a reject, by the gate's own arithmetic. Except when I actually read the eight answers instead of just their agreement score, three of them were pointing at things I hadn't considered at all: a missing measurement step behind a database-performance claim, a conflation of a plan's stated purpose with its surface description, and one persona's terse near-empty answer that turned out to be a legitimate signal — a comment that the question itself wasn't well-formed for consensus, not a dodge. A

On 1 August I opened an issue that was three sentences long. A hundred and one minutes later the feature was merged, and the document that got it there ran to 457 lines . I didn't write those 457 lines. In fact, I didn't have to write any more documentation, and not because I simply allowed Claude to run amok. Here is the issue in full — control-api#265 , 225 characters: control-api#265 — Manifest-backed dashboard feeds For each dashboard, auto create a manifest keyed by dashboard_id. For each sensor the dashboard uses, tag it to be included in the manifest. When a dashboard definition is updated, add / remove tags from sensors accordingly. From that genesis moment, this is the lifecycle of the issue all the way through to landing: Time (UTC) Event 14:25 Issue #265 opened — 225 characters 14:54 FEAT-0007 spec committed — 457 lines 15:35 Spec merged (PR #266) 15:51 Implementation committed 16:06 Implementation merged (PR #267, 15 files), issue closed The interesting part isn't the speed. It's the step at 14:54 that landed a previously non-existent spec document, and what happened in the twenty-nine minutes before it. The issue was never a specification I often write issues like this one...the way most people write shopping lists. Actuator address is not ensured? Baseline the trace correctly. With the pre-rolls, the frame-rate looks out. They're abbreviated to the point of being cryptic to everyone else. I write them this way deliberately: I'm usually mid-something else when I notice a problem, or have an idea for a better route to the solution. The cost of a full write-up right at that moment would be a fractured sense of flow. As most engineers will tell you, the transitions into and out of flow are the most disruptive parts of their working day. This terse form of issue-writing can be all you need, and it's worth being precise about why it works and the trade-offs it includes. It is not because "the issues are good enough". They aren't. When you pick one of these u

Introduction: The Debate Over Code Comments In the trenches of software development, a quiet but fierce debate rages: are code comments still relevant? On one side, the prevailing narrative dismisses comments as "mostly useless" —redundant, outdated, or worse, misleading. This perspective has gained traction, fueled by the rise of self-documenting practices like meaningful variable names and modular design. Developers, under the gun of tight deadlines, increasingly treat comments as an afterthought, if not a burden. The result? Comments are neglected, both in writing and reading, creating a self-fulfilling prophecy of their uselessness. But here’s the rub: this dismissive attitude is flawed. When used thoughtfully, comments are not just useful—they’re critical. The problem isn’t comments themselves but how they’re misused or ignored. Poorly written comments, lack of maintenance standards, and time constraints have deformed their purpose, turning a powerful tool into a liability. For example, a stale comment explaining a function’s behavior can lead a developer to misinterpret the code, causing bugs that cascade through the system. The mechanism here is clear: impact (misleading comment) -> internal process (developer misinterprets code) -> observable effect (bugs introduced) . The stakes are high. As software complexity grows and developer turnover accelerates, the need for clear, maintainable code becomes non-negotiable. Comments, when crafted with intent, act as a bridge between the code’s logic and the human mind, reducing cognitive load and fostering collaboration. Neglecting them risks eroding code readability, maintainability, and team productivity—a risk that materializes when a new developer inherits a poorly documented codebase and spends hours deciphering its intent. This investigation challenges the dismissive attitude toward comments, dissecting their underappreciated utility through real-world examples. By addressing misconceptions and promoting best pr

Originally published at https://ninadpathak.com/articles/technical-documentation-template/ . Creating documentation often forces several decisions at once: where readers begin, how they complete the first task, where exact details belong, and how they recover when a step fails. A template reduces that first pass to a structure you can inspect and adapt. I built this template to solve a narrow problem: an empty documentation repository leaves every contributor to invent navigation, page responsibilities, and release checks again. It provides five focused pages, a local validator, and a strict build path so the structure is useful before the product-specific writing begins. Download the technical documentation template Download the template Unpack the archive, then replace the placeholders with evidence from your product. The remaining sections show what belongs in each page and how to verify the result. What a technical documentation template should include A technical documentation template is a reusable starting structure for product or engineering documentation. It should tell a contributor where a reader begins, where they complete a task, where they look up stable details, and where they recover from a known failure. A table of contents alone cannot do that work. It can label a page “Getting started” without establishing prerequisites, a tested command, an expected result, or a recovery path. The starter contains five pages because they create a complete first route without pretending every product needs the same collection. Page Reader job Evidence to add before publishing index.md Choose the first useful task A direct route to the right starting page getting-started.md Complete first setup Prerequisites, a tested command, expected output guides/send-a-request.md Perform one bounded task A full request and response or observable state reference/configuration.md Look up stable details Names, types, defaults, and constraints troubleshooting.md Recover from a know

A pattern I’ve seen many times in software projects is that documentation starts too late and documents the wrong thing. A team ships a feature, the code works, the tests pass, and everyone moves on. Maybe someone adds a README section, maybe not. If they do, it usually explains how to run something, how to call an endpoint, or what a component does. That kind of documentation is useful, but it often misses the part future developers need most. It misses the decision. Six months later, someone opens the same part of the codebase and asks the usual questions. Why is this data model shaped like this? Why is this rule handled in the backend instead of the frontend? Why is this integration synchronous? Why does this permission check live here? Why did the team choose this simple approach instead of something more flexible? The code can show what exists, but it rarely explains why it exists. That is where a lot of engineering context disappears. The Problem Is Not Always Missing Documentation When people complain about documentation, the usual diagnosis is that there is not enough of it. The README is outdated. The setup instructions are incomplete. The API docs are missing examples. The architecture diagram no longer matches reality. All of those problems are real. But I think there is another documentation problem that is easier to miss: the docs describe the system without preserving the reasoning behind it. This matters because software is full of trade-offs. A piece of code may look strange because it was written badly, but it may also look strange because it was solving a constraint that is no longer visible. Maybe the team chose a simpler data model because they were still validating the product. Maybe they avoided a generic abstraction because they had only one real use case. Maybe they accepted duplication because the two workflows looked similar but were expected to diverge. Without the reasoning, future developers have to guess. That guessing creates waste. So

One of the most annoying parts of backend development isn't building APIs. It's keeping the...

The problem Recently I was looking for an npm package to generate OpenAPI (Swagger) documentation for my existing TypeScript project. My biggest requirement was TypeScript type-to-schema conversion: I already have all my request and response types, so why should I maintain the same schemas again in OpenAPI? Zod support would be a nice bonus. After trying most of the existing solutions, I found they generally fall into two categories: 1. Runtime frameworks The most popular example is tsoa . Honestly, tsoa is one of the best OpenAPI generators available today: it understands TypeScript well, generates schemas automatically and detects status codes. There are also contract-first libraries like ts-rest , Zodios and express-zod-api . However, none of these solutions are agnostic when it comes to how you write your code — they all dictate the shape of your routes. 2. Manual generators The best-known example is swagger-jsdoc. You write raw OpenAPI next to your code in JSDoc comments: /** * @openapi * /users: * post: * ... */ swagger-jsdoc is simple and framework-agnostic, but it's too verbose and knows nothing about your types. Then I found a similar tool that solved the verbosity problem: @visulima/jsdoc-open-api . It parses much more readable JSDoc tags: /** * POST /users * @summary Creates a new user. * @tags Users * @bodyContent {User} application/json - User object to create. * @bodyRequired * @response 201 - User created successfully. * @responseContent {User} 201.application/json - The created user object. */ But it still doesn't care about your types. User here is just the name of a component you have to define elsewhere in your document. Why not parse the actual types at generation time? That question inspired me to create Autoswag . The solution - Autoswag Describe your routes with readable JSDoc, and let the generator convert your TS types along the way. It doesn't affect your runtime code in any way, works with any framework, and even with vanilla JS. This is w

I’ve always disliked writing documentation. Not because it’s hard, but because it’s repetitive. You write a function, you describe what it does, you give an example, and then you realize you need the same thing in another language because half your users don’t speak English. So I decided to automate it. The result is an API that takes source code as input and returns a clean Markdown README, API reference, or inline comments — in any of 13 languages. No templates, no manual translation. curl -X POST "https://ai-code-documentation-generator.p.rapidapi.com/demo" \ -H "x-rapidapi-host: ai-code-documentation-generator.p.rapidapi.com" \ -H "x-rapidapi-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"code":"def add(a,b): return a+b","code_language":"python","doc_language":"en"}' { "success" : true , "documentation" : "# Add Utility \n\n ## Overview \n A simple function to add two numbers..." , "quality_score" : 9 , "target_language" : "en" } It auto-detects the programming language (Python, JavaScript, Go, Rust…) and spits out a polished doc. The English output is solid, but seeing it generate accurate Japanese or German READMEs from the same code still feels like magic. The Tech Behind It Backend: Python + FastAPI, hosted on Northflank. AI Model: DeepSeek (via API). The model actually understands code structure, so generated docs aren’t just generic wrappers. Language Detection: Pygments for syntax highlighting + language guessing. Caching: 24-hour cache to avoid redundant calls and save cost. Security: Sensitive strings (API keys, passwords) are automatically redacted from the output. The whole thing is open source: https://github.com/zhaochangbo888/docgen-api Why I Didn’t Just Use ChatGPT You could absolutely paste your code into ChatGPT and ask for docs. But integrating an LLM directly into a CI/CD pipeline, or a VS Code extension, or a platform that needs programmatic access gets messy with rate limits, authentication, and output consistency. This API giv

My project's docs had rules. "One document, one responsibility." "Split anything over 45 lines." I wrote that. The day before yesterday. Here's how that was going. Folders with no README (no index): 25 out of 37 The folder holding our engineering rules: 11 files, zero index Documents breaking the 45-line rule: 47 Largest offender: 1,203 lines Writing a rule down does not make it a rule. Obvious, I know. But there is something about being handed a list of 47 documents where you personally broke your own rule that stops being funny halfway down. (The me of two days ago fully intended to follow it.) I rewrote the rules themselves, and the rules file hit 150 lines The plan was already clear: let a machine enforce this. Fail CI. Which meant writing the rules properly first. README required, folder layout, update obligations, what CI actually checks. By the time it was all in there, the rules file was over 150 lines. The rules file was breaking the 45-line rule. Now, if you say "well, the rules file is special, it gets an exemption" — what have you just done? You have created the precedent "the rules are exempt," and it is permanent from that day. From then on, every time someone crosses 45 lines, they get to say "the rules file does it too." And they're right. So I split it. Eight files, all under 45 lines. If I can't follow my own rule, the rule was never worth writing. The moment CI landed, 63 existing violations bared their teeth On to the real work: write the checker, wire it into CI. Run it, and of course: 63 violations Everything fails. All red. Files I'm about to touch and files nobody has opened in months, equally red. Humanity is offered two choices here. Fix all 63 first, then turn on CI (including the 1,203-line monster) Add an ignore list, silence the 63, move on Tempting, isn't it? Option 2. It was to me. A .lintignore with 63 lines in it and a comment saying "remove later." So when exactly are you removing that list? Think about what that file actually is.

AI agents no longer just answer questions — they book meetings, approve refunds, call APIs, update records, and chain together dozens of small decisions into a single outcome. Most of the time, this works quietly and well. But when something goes wrong, a troubling question surfaces: why did the agent do that? For a large share of deployed systems today, there's no good answer. The reasoning, the data consulted, the tools invoked, and the intermediate steps simply weren't recorded. This is the problem of undocumented agent decisions — and it's becoming one of the central risks of the agentic AI era. What "Undocumented" Actually Means An undocumented decision isn't necessarily a bad one. It's simply one that can't be reconstructed after the fact. In practice, this shows up in a few common ways: Output without reasoning. The system logs what the agent did, but not the chain of thought, tool calls, or data sources that led there. Ephemeral intermediate state. Multi-step agent chains often discard the "scratch work" between steps — the very material that would explain a decision — once the final output is produced. Reviewer blind spots. A human approves a final recommendation without ever seeing the reasoning that produced it, which looks like oversight but isn't meaningful oversight. No durable storage. Logs exist for a few days or weeks, then age out — so when someone asks for the record months later, it's gone. The common thread is a gap between acting and accounting for the action. This Is Becoming Urgent A few forces are converging to make this problem harder to ignore: Agents are doing more, autonomously. As agents move from single-turn assistants to systems that independently call APIs, touch databases, and trigger downstream workflows, the number of undocumented micro-decisions multiplies. A single customer request might now involve a dozen internal steps, each a potential decision point. Incidents are already happening. Surveys of enterprise AI deployments in 2

There is a growing sentiment in engineering circles right now that documentation is a relic of the past. The argument usually goes something like this: We’re living in the era of agent-driven development. If an AI agent can read the raw source code or parse an OpenAPI specification instantly, why waste human engineering hours writing prose? Code churns too fast anyway, and human-written docs are outdated the second they’re committed. It’s an attractive, black-and-white view of the world. It’s also completely wrong. Chasing strict determinism in your source of truth is a pipe dream. Code and specs tell a system how something works, but they are fundamentally incapable of explaining why it was built that way in the first place. The Intent Gap: Why Code Isn't Enough Even if you’re building entirely for a downstream consumer of AI agents, there is a massive, structural gap between a raw API specification and an operational reality. Agents are phenomenal at pattern matching and syntax execution, but they struggle with architectural philosophy and human intent. We still need words to contextualize the boundaries. A spec can define an endpoint, its parameters, and its payload. What it can't capture is the nuance of why a specific architectural trade-off was made, or the implicit historical context of a legacy edge case. Prose provides the guardrails for non-deterministic systems. Even if that prose is ultimately consumed by a machine rather than a human, the written word remains the highest-leverage way to transmit intent. The Danger of Slop Describing Slop This doesn't mean we need to return to the days of manually maintaining massive, static wiki pages. Automation has a massive role to play here. Cascading automation—where documentation is dynamically generated alongside code changes—is incredibly powerful. But there’s a trap here: slop describing slop is entirely useless. If we completely hand off documentation generation to unchecked LLMs, we end up with a feedback loo

Documentation is often the first product a developer experiences. Before they see your architecture, your engineering culture, or your code quality, they interact with your documentation. If that experience is confusing, incomplete, or frustrating, many developers won't make it to their first successful API request. Over the past few weeks, I've been reviewing documentation from AI startups to understand what makes onboarding smooth—and where teams unintentionally create friction. While every company is different, the same patterns kept appearing. 1. Quickstarts assume too much Many Quickstarts jump straight into code without explaining prerequisites. Developers are expected to know: Where to get an API key Which SDK to install Required environment variables Authentication steps A Quickstart should help someone go from zero to a successful request with as little guesswork as possible. 2. Error messages aren't documented Developers don't judge documentation by how it works when everything goes right. They judge it by how quickly it helps them recover when something goes wrong. Instead of only listing error codes, explain: Why the error happens Common causes How to fix it What to try next Good troubleshooting documentation builds confidence. 3. Examples are incomplete Too many examples leave out important details. Developers shouldn't have to infer: Authentication headers Environment variables Request payloads Expected responses Examples should be copy, paste, run, and understand. 4. There's no clear learning path Documentation often feels like a collection of pages instead of a guided journey. A better structure might look like this: Quickstart Core Concepts Tutorials API Reference Advanced Guides Troubleshooting When developers always know what to read next, they make progress faster. 5. Documentation isn't written for AI-assisted development Today, developers increasingly rely on AI coding assistants. That means documentation should also be easy for AI tools to int

Developers are the world's most efficient skimmers. When someone lands on your repo, they're running a rapid mental triage: What does this do? (5 seconds) Can I run it? (10 seconds) Should I trust it? (5 seconds) If they can't answer all three within 20 seconds, they close the tab and move on. They don't owe you a careful read. They're choosing between your project and ten others. Most READMEs fail the triage test because they're written from the author's perspective, not the reader's. The author knows how it works, so they explain how it works. The reader doesn't know if it works at all, so they need to know what it does first. That's the gap. Let's close it. The README That Passes the 20-Second Test Every high-performing README follows a version of the same structure. The order is not arbitrary — it mirrors the reader's decision-making process. 1. One-Line Description (Not Your Project's Name) The name is already in the repo title. The first line of your README should be a plain-language sentence of what this thing does . ❌ SuperCache v2.0 ✅ A zero-config in-memory cache for Node.js that cuts database eat time by 60%. If your one-liner doesn't tell me what problem you're solving, I'm already skimming toward the exit. 2. A 30-Second "Why This Exists" Paragraph Two to four sentences. What problem does this solve? Who is it for? Why this over the alternatives? This is not a marketing pitch. It's a fast filter. You want the right people to know immediately that this is for them — and the wrong people to know it's not. 3. Demo / Screenshot First — Before Installation This is the most skipped section in most READMEs. It shouldn't be. A GIF, screenshot, or three-line code output does more work than five paragraphs of description. Show me what success looks like before you tell me how to get there. If I can see that your output solves my problem, I'll read every word of your installation guide. 4. Installation — Zero Assumptions Assume your reader is smart but unfamiliar

AI is changing how we build software, but I think a lot of developer tools are solving yesterday's...

Treating docs as a product When documentation lives as an afterthought, it shows. Pages drift out of date, examples break quietly, and release notes scatter across a dozen places no one can find. The fix is not a weekend cleanup. It is a decision to treat docs the way you treat any product people depend on: someone owns it, it has standards, and it gets maintained on purpose. That is the decision I made when the docs came to the Developer Relations team at the end of 2025. Not "let's tidy this up," but "this is ours now, and we are accountable for whether a developer can actually build from it." The work, in the repository The honest record of what a team does to a codebase lives in its git history, so that is where the story starts. Comparing the six months before the handoff to the six months since: Before vs. Under DevRel: Commits: 476 → 1,900+ Merged pull requests: 145 → 447 Unique contributors: 21 → 64 A repository that averaged fewer than 500 commits over half a year is now past 1,900 in the same span. The contributor count tripled, because we treated the docs as something the whole community could improve, not a walled garden. This is what a team that decided to do the work looks like when you measure it. Our proudest metric is what was cut In six months, we added roughly 339,000 lines and removed roughly 281,000. That near balance is the point. A neglected docs site accumulates: dead pages, stale tutorials, examples that no longer compile, three slightly different explanations of the same concept. Adding more on top of that does not help anyone. So we cut nearly as much as we wrote. We rebuilt the Hello World walkthrough from 1,300 lines down to about 300 without losing a thing. We consolidated scattered release notes into a single clean reference. A docs site is judged by what a developer can find and trust, not by how much sits on the shelf. A library you can learn from At the start of the year, the examples library had effectively one usable entry. Today,

The Runbook That Lied to Me at 3am The pager went off at 3:14am for a wedged OpenStack Neutron agent. I did what any tired engineer does: I opened the runbook. It told me to restart a service that had been renamed eighteen months earlier, pointed at a Grafana dashboard that 404'd, and assumed a network topology we'd migrated off of two quarters back. The runbook wasn't just unhelpful. It was actively lying to me, and I burned twenty minutes trusting it before I gave up and went to read the source. That's the real problem with documentation. It isn't that we don't write it. It's that the moment we finish writing it, it starts rotting, and the cost of keeping it fresh is high enough that nobody pays it until the document has already betrayed someone at 3am. A runbook your team doesn't trust is worse than no runbook, because no runbook at least forces you to think. This is where AI actually earns its keep in a platform org, and not in the way the marketing decks suggest. AI is not going to own your documentation. It's going to do the tedious first-draft labor — turning a resolved incident, a chunk of shell history, or a deploy diff into a structured skeleton — so a human engineer can spend their scarce attention on the part that matters: verifying the commands, marking what's unproven, and editing the robotic tone out so the team actually reads it. AI drafts. You verify and sign off. That distinction is the whole game. Why "Humanizing" AI Is the Job, Not a Slogan Let me be precise about what I mean by "humanizing AI," because the phrase gets abused. I don't mean making AI sound human to fool a reader. I mean keeping a human in the loop as the editor and owner of record, and doing the unglamorous work of turning a competent-but-soulless machine draft into something a colleague trusts. Two things break trust in AI-drafted docs, and both are fixable by a human pass: Unverified claims stated with confidence. An LLM will happily tell you to run systemctl restart neutron-l3-