Articles

Notes, tests, and arguments.

A tutorial should do more than run, and an explanation should do more than agree with the first page of search results. These are my arguments about developer content, documentation, and the AI systems I build around them.

Runbook Template and Example: Steps an On-Call Agent Can Follow
A Markdown runbook template where each step has a command, its expected output and a branch, with a tested Postgres example and a checker to run first.
10 min read
Release Notes Template: Copyable Markdown With a Pre-Publish Check
A release notes template in Markdown that puts the upgrade decision first, with a filled SDK example and a checker that fails a note missing its rollback line.
6 min read
Quick Start Guide Template: Write a Quickstart Developers Can Run
A quick start guide template for developer products, with a filled example against the GitHub REST API and a checklist to run before you publish.
5 min read
MCP Server Tutorial: Build a Docs Search Server in Python
Build an MCP server in Python, test it without a model, and see how numbering a tool's output changed whether Claude cited the right line in a test run.
9 min read
llms.txt: What It Is, What It Does, and Four Real Files Checked
What an llms.txt file is, what the proposal requires, what Google, Chrome and server logs say about its use, and four real files checked against the proposal.
5 min read
Design Doc Template: Sections, a Filled Example and a Review Check
A design doc template in Markdown with goals, non-goals and a required "do nothing" alternative, a filled example, and a checker to run before review.
5 min read
CLAUDE.md and AGENTS.md: Which File Loads, and a Template
Which coding agent reads CLAUDE.md and which reads AGENTS.md with default settings, tested in four repositories, plus a copyable AGENTS.md template.
6 min read
Claude Code Subagents: What Each One Sees, With a Tested Example
What a Claude Code subagent starts with and when to pick one over a skill or hook, with a link-checker subagent tested in Claude Code 2.1.308.
8 min read
API Documentation: What to Include, With a Tested Reference Example
What API documentation includes, page by page, and a complete reference entry for one endpoint that a script checks against the running service.
6 min read
GPTBot, ClaudeBot and OAI-SearchBot: AI Crawlers in robots.txt
Which robots.txt rules block AI training crawlers like GPTBot and which block AI search, plus what 12 developer documentation sites allow.
8 min read
AEO vs GEO vs SEO: What Changes for Developer Docs
What AEO, GEO and SEO each mean, what Google and OpenAI document about AI search, and six checks that decide whether developer docs can be found and quoted.
5 min read
Code Documentation: Comments, Generated Reference, and External Guides
Decide what belongs in code comments, generated reference, and written guides so each reader can find the right kind of answer.
5 min read
How to Write Task-Based Documentation Headings
Write documentation headings that tell a reader which task, decision, concept, or recovery path a section covers.
5 min read
Accessibility Testing for Documentation: A Release Checklist
Test developer documentation for release-blocking accessibility failures in structure, code, links, visuals, keyboard use, and rendered output.
6 min read
Internal vs. External Documentation: What Belongs Where
Internal vs. external documentation, with a decision table for incidents, architecture, auth and releases: what goes public, what stays private, what splits.
6 min read
What Is Technical Documentation, and What Should It Include?
Technical documentation explained: the document types it includes and the reader task each one owns, in a table you can check a docs set against.
5 min read
Types of Technical Documentation: 8 Essential Types, Plus Agent Instructions
Understand the main types of technical documentation, study useful examples, and build a documentation system for users, teams, and coding agents.
7 min read
Technical Documentation Best Practices, Tested on Real Developer Docs
Use a tested review card to make documentation tasks, failure states, limits, and ownership clear before readers need support.
4 min read
Technical Documentation Template: Build Product Docs With a Tested Structure
Download a technical documentation template, learn what each page must prove, and turn its placeholders into trustworthy product docs.
6 min read
Organize Documentation Around Reader Routes, Not Your Org Chart
Reorganize a documentation site around reader routes, canonical answers, tested labels, and direct redirects instead of mirroring the org chart.
12 min read