标签：#document

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-

AI coding agents are becoming better at changing software. That is no longer the hardest problem. The harder problem is keeping the repository understandable after those changes land. Code changes quickly. Documentation often does not. Product intent lives in chat history. Architecture notes fall behind. Reviewers can inspect the implementation diff, but they often cannot see whether the product promise, engineering contract, and repository workflow are still aligned. Truthmark is built for that gap. It is a Git-native workflow layer for AI-assisted software development. It installs repository-local truth workflows so AI agents can keep canonical truth docs aligned with functional code changes, while humans still review normal Git diffs. Truthmark 2.2.0 takes a significant step forward: it separates product truth from engineering truth. That may sound like a documentation detail. It is not. It is a workflow boundary for AI coding agents. Why truth needs lanes Most documentation systems treat “docs” as one surface. That works until AI agents start using those docs as operational context. A product promise and an implementation detail are not the same kind of truth. A product doc should say what must be true, why it matters, who benefits, what boundary is being protected, and what success means. An engineering doc should say how the repository currently realizes that promise: the behavior, contract, architecture, workflow, operations, tests, and source-backed implementation facts. When those two kinds of truth collapse into one file, the result is usually weak in both directions. Product truth becomes a summary of implementation mechanics. Engineering truth becomes a detailed version of product rationale. Neither is ideal for humans. Neither is ideal for agents. Truthmark 2.2.0 introduces explicit product and engineering lanes so agents can reason about these surfaces separately. The core rule is simple: Product truth says what must be true and why. Engineering truth

Last year, I examined RUM indexes within this series on multi-key indexing, demonstrating that they cannot substitute MongoDB's compound indexes for sorted queries. A year later, Microsoft has fixed this in the DocumentDB extension for PostgreSQL with an Extended RUM index that preserves the ordering of the keys, allowing an ordered scan rather than a bitmap scan. Let's revisit our pagination query to see how it performs now. I start a container with the latest DocumentDB (version v0.112-0 from May 26, 2026): docker run -d --name documentdb-local -p 10260:10260 -p 9712:9712 ghcr.io/documentdb/documentdb/documentdb-local:latest --username franck --password franck --start-pg I can connect to PostgreSQL on port 9712, where many extensions are installed, including the extended RUM index: docker exec -it documentdb-local psql -p 9712 postgres psql ( 17.10 ( Debian 17.10-1.pgdg13+1 )) Type "help" for help. postgres = # \dx List of installed extensions Name | Version | Schema | Description ------------------------- +---------+------------+------------------------------------------------------------ documentdb | 0.112-0 | public | API surface for DocumentDB for PostgreSQL documentdb_core | 0.112-0 | public | Core API surface for DocumentDB on PostgreSQL documentdb_extended_rum | 0.112-0 | public | DocumentDB Extended RUM index access method pg_cron | 1.6 | pg_catalog | Job scheduler for PostgreSQL plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language postgis | 3.6.3 | public | PostGIS geometry and geography spatial types and functions tsm_system_rows | 1.0 | public | TABLESAMPLE method which accepts number of rows as a limit vector | 0.8.2 | public | vector data type and ivfflat and hnsw access methods ( 8 rows ) postgres = # I can also connect to the MongoDB-compatible API: docker exec -it documentdb-local mongosh -u franck -p franck 'mongodb://localhost:10260/?tls=true&tlsAllowInvalidCertificates=true' Current Mongosh Log ID: 6a0b3b537d2a1c3471d1a7ba Connecting to: mo

A new documentary chronicles how the app became a stand-in for American anxieties about social media, China, and political power.

Bilingual post · Post bilíngue Jump to: English · Português English {#english} Navigating the Reorganized CrabPascal Docs Phase 1 of this blog series covered fundamentals — CLI, lexer, sprints, and how to contribute. If you read Contributing to CrabPascal: Get Involved , you already know where the repo lives and how to open a PR. Phase 2 is different: we walk the Mintlify documentation site the way a new teammate would, mapping each article to the pages you actually need in daily work. The live docs live at crabpascal.mintlify.app . The source is under mintlify/ in the Bitbucket repo. Think of Mintlify as the canonical handbook; Dev.to posts are the guided tour. Why the docs were reorganized CrabPascal grew from a v1.5 experimental interpreter (October 2025) to v2.22.0 with sprint-driven releases, Horse E2E tests, and honest build-exe . Old folders like documentation/00-INICIO/ still exist in git history, but Mintlify groups content by job to be done : You want to… Start here Install and run Quickstart See current capabilities Project status Understand architecture Architecture Follow releases Changelog Historical reports from v1.5–v2.8 remain under Histórico with archive banners — useful for context, not for "what works today." The home page is your compass Open the Mintlify index . It shows v2.22.0 at a glance: real diagnostic spans, System.* RTL, Unicode strings, dual-mode run/build, and Horse HTTP parity. Four cards link to quickstart, changelog, sprint roadmap, and technical-debt backlog. Essential CLI commands are listed once: crab-pascal check programa.dpr # diagnostics with line/column crab-pascal run programa.dpr # interpreter / runtime crab-pascal build-exe programa.dpr # native binary via C toolchain Bookmark this page. When someone asks "is feature X done?", check status + changelog before diving into Rust sources. The documentation map: question-driven navigation The page essentials/documentation-map is the "I want X, go to Y" cheat sheet. It answers sc

Architectural change cases extend architecture decision record (ADR) thinking by evaluating how decisions may evolve over time. Change cases expose hidden assumptions and help teams estimate the reversibility and cost of change. By Pierre Pureur, Kurt Bittner

My father worked in IT for over thirty years, and growing up around that shaped how I thought about computers. The earliest memory I have is sitting in my father's lap as he does something on his computer. One of the oldest photos I have is of me sitting on a chair in front of a computer. I grew up idolizing him. I switched to Linux when I was 12, by myself. I taught myself scripting, picked up programming basics, and spent more time in a terminal than most adults I knew. I have memories of sitting on the roof at 13 with my laptop, trying to crack my neighbor's WiFi with aircrack-ng (they were aware of my endeavors). However, growing up in a politically volatile neighborhood (Lyari) also made me politically aware and literate from a young age. With that, I developed an interest in political science and philosophy. I sat my A levels in economics and sociology, and I did not look back. For the next few years, the technical side of my life became just a habit rather than a professional direction. Then I realized I do not have to choose one or the other. I can carry on doing both. Today, I am an academic and technical editor. The social sciences gave me the writing skills: reading long blocks of dense theory, explaining abstract concepts in plain language, writing long analytical essays. And I understand technical concepts well enough to work with them seriously. I thought of synthesizing both. When I started building a technical writing portfolio, cybersecurity documentation felt like a natural place to go. Not because I had operational experience, but because I had grown up adjacent to that world. I understood the culture, the tooling, and the mindset, even if I had never worked a SOC shift. I knew I wanted to cover security documentation. Security teams produce some of the most consequential written work in any organization, and most of it is poorly structured, inconsistently formatted, or written for the person who already knows the answer rather than the person who

I learned this the hard way: when an LLM says “it matches the docs”, it can still be wrong for a boring reason—it didn’t read the part that matters. I’m building a small SaaS (checklists as a service). No users yet. Plenty of documentation already. And at some point my docs stopped being an asset and started turning into a liability. This is the story of how I rebuilt my documentation so that an LLM could actually read it end-to-end —and how that restructure helped me. The moment I got scared: “silent misses” The docset grew. I kept asking the LLM to verify tasks against it. And then I noticed a pattern that felt worse than hallucinations. Not “the model invented stuff”, but “the model confidently said it matches ”—while quietly missing exceptions, prohibitions, and thresholds. Keyword scanning instead of reading. I called it silent drift : code slowly moves away from conventions, while the invariants remain only in my head. In a project with roles, audit, and CI/CD security gates, that kind of drift isn’t “just messy docs”. It’s how you lose the ability to implement and review changes consistently. I couldn’t do it manually (and I couldn’t delegate it fully) I knew I had to redo the documentation. But I also knew I couldn’t realistically do it all by hand. At the same time, I couldn’t just tell an LLM: “Rewrite everything according to approach X.” Not enough context, too easy to lose control. So I went with a third option: build a reliable process out of unreliable components— me + an LLM . Step 1: I separated my docs into domains (and forced the model to actually read) First, I extracted domain areas from the old documentation—the vocabulary I was using to describe the project and its parts. I tried to keep domains mutually independent (so the overall framework stays holdable in my head). Then I ran the same loop for each domain: I asked the LLM to read all old docs carefully and extract requirements for that domain. I moved those requirements into a dedicated fil

Podlite 2.0 is tagged. Podlite is a block-based markup language built around typed blocks and explicit boundaries — the same document is meant to read cleanly whether a person or a tool parses it. This release adds eight blocks and attributes and changes two parsing rules. The specification is at podlite.org/specification ; the full changelog sits inside the spec under =head2 v2.0 . The Coming in Podlite 2.0 article from the review window covered what is new in depth. This post focuses on what to do now: how to migrate existing documents and where to find the rest. For most documents the answer is short — a well-formed v1.0 document renders unchanged under v2.0. Breaking changes Two changes parse differently than before. Neither touches a well-formed document — if anything needs updating, it is a parser, not your text. Legacy attribute syntax removed A few outdated string attribute formats are gone. The bracket form ( :key<value> ) and the parenthesized form ( :key('value') ) remain. If a document uses the current syntax, nothing changes. =include is now a directive =include always behaved like a directive, but the spec previously listed it under block types. Tokenization rules differ between directives and blocks. Parsers built against the v1.0 spec must move =include into the directive dispatch path alongside =config and =alias . For document authors: no change. =include still takes the same syntax and produces the same output. The reclassification matters only for tools that build ASTs. New features at a glance Eight additions ship in v2.0. Existing documents render unchanged. =boundary : a typed section divider. Renders as a horizontal rule, exposes structure to tools. =set : pre-configure attributes for the next block. Multiline values, inline markup, lexical scope. G<> + :masked : content masking. Inline mark or whole-block attribute; hidden by default, revealed by render condition. =data-table block: renders CSV or TSV as a table. Three source forms (inline b