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.
Hire me: email hello@ninadpathak.com, or book a 30-minute call at https://zcal.co/i/AGG1iJtv
A Request Is Not a Reader: What Fern's Agent Traffic Data Shows
Fern says agents are now over half of the requests to the docs it hosts. A close read of the numbers, what they change for docs teams, and what they leave out.
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.
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.
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.
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.
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.
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.
Code Documentation: Comments, Generated Reference, and External Guides
Code documentation has three homes: comments, generated reference and guides. Real examples, where each fact belongs, and whether agents should write comments.
How to Write Task-Based Documentation Headings
Write documentation headings that tell a reader which task, decision, concept, or recovery path a section covers.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The Case for Shorter Technical Documentation
Why shorter technical documentation works better, why AI-written docs run long, how to cut a page without losing detail, and when length is earned.
Writing Release Notes That Developers Trust
Write release notes that let developers assess upgrade risk, understand product impact, and migrate without surprises.
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.
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.
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.