标签：#document

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