Articles / Technical Documentation

Technical Documentation

Documentation is where a product either teaches people to win or leaves them alone with the error. I care about that choice.

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
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
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
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
Compare internal and external documentation, decide where each page belongs, and split shared subjects without exposing private operating context.
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
Documentation Review Should Start With the Product, Not the Prose
Review documentation in four passes: product truth, reader route, rendered behavior, and release state, before polishing prose.
12 min read
Technical SEO Checklist for Documentation Sites
Technical SEO for developer documentation: crawling, rendering, indexing, canonicals, internal links, Core Web Vitals, structured data, and search visibility.
13 min read
The Case for Shorter Technical Documentation
I think technical docs are often too long for the wrong reasons. Here’s why shorter docs usually work better, and where longer docs still earn their keep.
9 min read
Writing Release Notes That Developers Trust
Write release notes that let developers assess upgrade risk, understand product impact, and migrate without surprises.
12 min read
How to Write a Technical Tutorial That Actually Teaches
Write a technical tutorial that takes one reader from a clear starting point to a tested, useful result.
6 min read
Developer Onboarding Documentation: End It in a Merged Change
Developer onboarding documentation should take a new engineer from a clean machine to a safe first merged change, with one setup path and a check after each step.
11 min read
How to Write a Changelog That Developers Actually Read
Write a changelog that helps developers assess an upgrade, find breaking changes, and understand what each release means for their code.
11 min read