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.

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 helps a developer decide, start, use, and recover from a product. Choose each page by the task it owns.
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.
6 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
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
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
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 Docs Should End in a Merged Change
Build developer onboarding docs around one supported setup path and a safe first merged change, with proof and recovery at each fragile 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