Runbook Rot: Three Fingerprints of Stale CI Docs and the Check That Catches Each
A runbook is the only document in your repo that gets read at 3 a.m., under adrenaline, by someone who trusts it. When the code is stale you get a b…
Open Source
⚑ Report a ProblemLatest Open Source news from Tech News
All topics
AI
agents
ai
api
architecture
automation
backend
beginners
career
database
devchallenge
devops
discuss
javascript
linux
llm
machinelearning
mcp
opensource
performance
productivity
programming
python
react
security
showdev
testing
tutorial
typescript
webdev
I replayed 7 repos' READMEs in fresh clones. 2 of them fail their own quickstart.
Your README is a promise nobody tests. Setup instructions rot silently. You rename a script, add an env var, switch a package manager, and the quick…
We deleted our docs framework. The replacement is 400 lines of Next.js + MDX.
TL;DR A small docs site needs 5 packages : next-mdx-remote , remark-gfm , rehype-pretty-code , shiki , gray-matter . One route ( app/docs/[[...slug]…
Freeze Tutorial Samples Before a Model Drafts the Walkthrough
Models may draft tutorial narration, but they must not invent the samples that the narration claims to demonstrate. A human-owned fixture ledger sho…
Server, crates and docs
As I've had a pretty busy period, I haven't had the chance to post anything new here, and I only managed to get a few things done on the actual codi…
Learning to Fit the Room: A Skill I Built to Practice Concision
How working on my own communication led me to build Concision, a portable skill for AI agents. I’ve received the same kind of feedback more than onc…
Modeling Waterfront Assets with Shapezo: A Typed Content Pipeline for Docks, Piers, and Wharves
Most port documentation fails for a boring reason: it is unstructured prose about structured things. A dock is a graph. It has a deck, a piling fiel…
Terminology drift is the quiet tax on a large content corpus
Translation bugs that crash are easy. You find them, you fix them, they stay fixed. The expensive problem is slower: the same concept, translated th…
Best Data Warehouse Schema Documentation Tools (2026): SQLDBM, dbt, DataHub, Atlan & SchemaSpy Compared
Schema documentation used to be the thing teams promised to do "next sprint" and then never did. In 2026, that excuse doesn't hold up. Warehouses ar…
Specification: Agentic Docs-as-Code Architecture Pipeline
Overview This specification establishes an automated, agent-driven software architecture documentation ecosystem. The framework integrates strict st…
Step 3 — Documentation Generation
Exactly. Step 3 is where we finally produce the human-readable architecture document . The important rule is: Step 3 must not rediscover the archite…
Build a Knowledge Layer for SQL Agents with OKF (Part 2)
You connect an AI agent to your shop's database and ask a simple question: "How many active customers do we have?" The agent looks at the tables: cu…
I audited marshmallow's docs: 184 missing docstrings, 65 stale. Here's the tool I built to fix that
Most teams have one repo nobody wants to touch. It works, it matters, and the people who understood it have moved on. Half the functions have no doc…
The Globe: Following Your Reasoning Into Other People's Repositories
Keep the Why records why a codebase is the way it is. Decisions can cite decisions in other repositories. The Globe follows those citations outward,…
첫 번째 스프린트 이후에도 프로젝트 참조 링크를 유용하게 유지하는 방법
프로젝트 링크는 결정 기록보다 빠른 속도로 늘어나는 경우가 많다. 첫 번째 스프린트만 지나도 프레임워크 문서, 패키지 안내, API 예제, 디자인 메모, 버그 보고서, 배포 가이드, 과거 내부 논의까지 다양한 주소가 한곳에 쌓인다. 처음에는 각각의 링크에 분명한 필…
Implementing Modern Documentation Search for Developer Portals
When developers or users land on a technical portal, their primary goal is to find precise answers quickly. A poorly implemented search bar leads to…
The Future of Product Documentation
Your next customer might integrate your product without ever visiting your documentation site. Their coding assistant will read it for them, choose…
The Markdown File Changed Even Though I Only Edited One Word
I once opened a Markdown file, changed one word and saved it. The preview looked exactly as expected. Then I checked the Git diff and found changes…
Stop Making AI Agents Grind Through Huge Codebases — I Built a Deterministic Wiki Build System for Them
Joining an unfamiliar codebase, what you want isn't more code — it's a wiki that explains how the thing actually works: which modules exist, where t…
Turn Parser-Visible Flags Into a Config Reference Grid; Sign Defaults and Secret Classes
Configuration reference pages fail when generated prose is treated as the source of production defaults, secret classes, or deprecation windows. A p…
Split Config Docs Into Extracted Keys and Operator-Signed Constraints
Config documentation fails most often when a generated catalog silently absorbs production promises that nobody reviewed. Parser extraction can list…
How i documented a Broken codebase without losing my mind.
If you want to use it straight away | Link here I believe we achieved a point in tech where having a broken codebase that started as an MVP and evol…
Self-Improving Docs, Part 1: Automatically Turning Documentation Gaps Into Pull Requests
This blog is Part 1 of my series, Self-Improving Docs : Turning Gaps Into Pull Requests, on how I run documentation as a self-updating system. In Pa…
Your README's code examples are untested — here's how I test mine in any language
Your README is full of code — shell commands, config snippets, >>> sessions, example output. And unlike the rest of your codebase, none of…
Architecture: Write It Down Before Rewriting
Part of the "How to bring order to a project" series — the architecture track. Same context: a growing gamedev project, about twenty services on dif…
"Two readers, two documents"
Today, in the Matching repo, there are two files called README.md with the same modification time: 2026-08-18 04:43:43 for the one at the root, 04:4…
How Mautic pairs Promptless with human review to catch up on docs
Originally written for Mautic . A developer just merged a big feature into an app repo, and 'update the docs' lands somewhere on their to-do list. W…
The Hell Documentation
Anyone who has worked with OS development, especially beginners like me, has probably encountered problems with documentation. I am not writing this…
All 23 of my line-number citations were wrong, and the coverage check could not notice
A table in my spec cited a source file by line number, 23 rows of it. Every one was off by one or two. The coverage check next to it had been green…
AI Agents Don't Read Your API Docs Like Developers Do
I have spent a lot of my time writing API documentation, and I used to think that I understood what makes an OpenAPI specification good until AI cam…