标签：#documentation

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

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