DEV Community: Ninad Pathak

API Documentation Best Practices: Reference, Guides, and Working Requests

Ninad Pathak — Wed, 19 Aug 2026 18:01:26 +0000

Originally published at https://ninadpathak.com/articles/api-documentation-best-practices-reference-guides-and-working-requests/.

An API portal can list every endpoint and still leave a developer unable to send a request. The missing work is usually distributed across a quickstart, reference, and error guidance, which makes an incomplete path look finished in a navigation tree.

The reader outcome is concrete: someone with a test credential can make one request, inspect its exact contract, and recover from a predictable failure. That path is the unit to design and test before adding more endpoints.

API documentation system: assign each page a job

A quickstart owns first success. It names the access required, gives one complete request, shows an expected response, and links to the next task before the reader must hunt for vocabulary or configuration.

Reference owns exact behavior. The OpenAPI Specification models paths, operations, parameters, request bodies, responses, security, and reusable components, which makes it a strong contract baseline when the source description is reviewed with the API.

Reader moment	Page that owns it	Evidence that the page works
I have credentials and need a first response	Quickstart	Complete request and expected response
I need the exact field or limit	Reference	Parameter, type, default, constraint, and response schema
The request failed	Error or troubleshooting guide	Status, cause, diagnostic detail, recovery, and escalation boundary
Product behavior changed	Migration guide or release note	Affected version, required action, and replacement path

Stripe's API reference gives readers a route through objects, endpoints, parameters, and response data. Its reference strength does not remove the need for a guide that explains which request is worth sending first.

Write one working request before expanding the reference

Choose a request with a safe test credential, a small response, and a result a reader can recognize. A list endpoint is often a useful first move because it proves authentication, base URL, method, and response handling without asking someone to change production data.

curl --request GET \
  --url https://api.example.com/v1/projects \
  --header "Authorization: Bearer $API_TOKEN"

The guide needs the expected result beside the command. If a successful response contains projects, say so, then link limit, pagination, field definitions, rate behavior, and every response shape to reference where they can stay exact.

A copyable request is not sufficient when its failure state is opaque. Postman describes API documentation as covering endpoints, methods, resources, authentication, parameters, headers, and examples, and each item should remove a decision the reader would otherwise have to guess.

Keep reference and guides connected without merging them

Reference answers questions that have stable names. It should make the endpoint, authentication scheme, parameters, request body, response schema, errors, and limits easy to scan without turning every page into a tutorial.

A guide connects those details into a task. Authentication belongs in both places when the guide explains how to obtain and send credentials while the reference records header format, scope behavior, and error schema.

The strongest objection is that an OpenAPI-generated reference should eliminate this split. Generated reference can remain more complete as endpoints change, yet it cannot decide which object proves a new integration works, whether a retry is safe, or which production choices belong after the first response.

Keep the generated contract close to the source and keep the guide close to the reader's task. That boundary becomes more important as an API gains pagination, webhooks, SDKs, version changes, and different authentication modes.

Link the API documentation route to its next decision

Link from the quickstart to the exact endpoint reference after the reader has a request to inspect. Link from reference to a guide when the reader needs a workflow, and link each recoverable error to a diagnostic path instead of a generic support page.

The documentation template shows the smaller site structure that separates a first task, reference, and troubleshooting. The documentation organization guide shows how those routes become navigation without creating duplicate homes for the same task.

Version changes need their own route because a valid request can become unsafe when its credentials, field names, or response behavior change. Use the product-version documentation guide to keep supported instructions reachable and to give retired routes an honest migration destination.

Build the first request path before filling an API portal with pages. When a developer can get credentials, send one safe request, inspect the contract, and recover from a known failure, the rest of the documentation has a route that can grow without losing its reader.

Built while writing this: the technical writing linter. Free, runs in the browser, no signup.

How to Document Multiple Product Versions

Ninad Pathak — Tue, 18 Aug 2026 18:01:21 +0000

Originally published at https://ninadpathak.com/articles/how-to-document-multiple-product-versions/.

A version switcher can make incompatible instructions look like interchangeable pages. A current page, a supported older page, and a retired page need different URL behavior before a canonical tag or redirect can be correct.

The policy is simple: keep instructions reachable and self-canonical while the product version remains supported. Redirect a retired task only when the destination still gives the reader a valid path, and preserve a historical version when its instructions remain useful evidence rather than a trap.

Product documentation versioning checklist

Use this table to establish the policy before configuring navigation or search metadata. It separates a version that a developer can still use from one that only needs a record of where the old URL went.

Version state	URL behavior	Canonical	Reader-facing label
Current supported version	Stable, direct URL	Self-canonical	Current
Older supported version	Stable, direct URL	Self-canonical	Supported version
Retired version with an equivalent replacement	Permanent redirect to the replacement	No page to canonicalize after redirect	Retired and redirected
Historical version with distinct instructions	Stable, direct URL	Self-canonical	Historical or unsupported

A canonical consolidates duplicate or very similar pages. It is not a safe way to merge materially different setup steps, API fields, authentication rules, or migration boundaries.

Audit documentation versions before choosing redirects

Start by treating each version as a reader task. A path is distinct when following one version's instructions against another version can fail, change data, or produce an unsupported integration.

Google's canonicalization guidance frames canonicalization as a preference among duplicate or very similar URLs. That boundary matters in product documentation because versioned pages often look similar in a template but carry different behavior.

Define which versions are supported

Publish a small support matrix close to the version switcher and on the page itself. State the version, support state, relevant release date, and the route to migration guidance when the page is no longer current.

The word latest is not enough. It becomes misleading as soon as a developer lands on a bookmarked versioned URL or copies a command into a long-running service.

Keep supported versions on distinct self-canonical URLs

A supported version needs a stable URL, a visible label, and its own self-referencing canonical. That gives the developer a link they can share and stops the current version from silently claiming ownership of instructions that are still valid elsewhere.

Docusaurus versioning preserves a copy of documentation when a new version is created, which is the useful model here. The preserved set remains inspectable as the current documentation continues to change.

Redirect only when the replacement preserves the task

A permanent redirect is a strong signal that the target replaces the original URL. Google's redirect documentation describes redirects as a canonicalization signal, so send a retired documentation URL to a target that can actually replace its reader outcome.

Redirecting /docs/v1/authentication/ to a general release note fails that test. Redirect it to the equivalent current authentication guide only when the current guide includes the migration boundary, or keep a historical page that says why the old path no longer works.

Link readers to the right documentation version

A version switcher should change the page, not only the label. Keep version choices in ordinary crawlable links, then make the active version visible near code blocks, prerequisites, and migration notices.

The documentation homepage guide explains why a route label needs to predict the page that follows. Apply the same standard here: v2 supported documentation is useful, while Other versions makes a developer open another interface before learning whether their task is covered.

The documentation SEO guide shows how to audit the canonical, title, links, image text, and sitemap after the route policy is settled. Version policy comes first because search metadata cannot repair a path that sends a developer to the wrong instructions.

Preserve historical pages that still explain a real state

An unsupported page can still earn a stable URL when it documents a deployment a reader must maintain, a security boundary, or a migration that cannot be reversed. Mark its support state plainly and link to the current version without pretending both pages say the same thing.

The competent objection is that keeping old pages adds maintenance and duplicate-content risk. That is true when old pages are vague copies, but deleting or canonicalizing a page with different working instructions sends developers to an answer that may be wrong for their installed version.

A versioned documentation system works when the URL, page label, canonical, redirect behavior, and migration path tell the same story. Start with the routes developers already bookmark, then test the policy whenever a release changes which instructions remain safe to follow.

Built while writing this: the AI Overviews extractability checker. Free, runs in the browser, no signup.

What a Documentation Homepage Must Help Users Do

Ninad Pathak — Mon, 17 Aug 2026 18:02:53 +0000

Originally published at https://ninadpathak.com/articles/what-a-documentation-homepage-must-help-users-do/.

A documentation homepage has a narrow job: help someone choose a useful next move before they understand the whole product. I reviewed Stripe, GitLab, GitHub, Chrome, and Google Maps documentation homepages while building the route audit below, and the layouts vary far more than the underlying behavior.

Each homepage gives a reader a route, not just a collection of things to browse. That distinction is what separates a documentation landing page from an equal-weight card wall.

Give the documentation homepage four reader routes

A homepage should help a new user start, a returning user resume work, a blocked user recover, and an evaluator understand the product surface. These are jobs, not mandatory visual sections.

Reader situation	Homepage promise	A useful destination
New to the product	Complete the first supported result	Quickstart or first request
Returning to implementation	Find an exact object or workflow	API reference or task guide
Blocked by a failure	Recover without searching the whole library	Troubleshooting or error guide
Evaluating the product	See which capability route applies	Product overview or capability guide

The five homepages I inspected make different design choices, but they all make at least one route obvious. Stripe leads toward getting started and a runnable example, while GitLab places frequent answers ahead of broader product areas.

GitHub groups its library by jobs such as collaborative coding and CI/CD. Google Maps pairs a first action with capability routes, which keeps product discovery from replacing task completion.

Make the first action more prominent than exploration

A new reader often arrives with a simple question: can I make this work? Put the shortest supported path near the top, then let broader product exploration follow.

Chrome’s documentation homepage establishes what the library contains, then gives product areas clear entry links. The point is not to copy Chrome’s layout.

Make the first decision smaller than “choose from everything we have.”

A card wall fails when every destination carries the same visual weight, even though one route is the safe first step and another is a niche reference page. Cards are fine when they identify a reader, a job, and a destination.

Make labels describe the route

A reader should be able to predict the next page from the label alone. Send your first request and Troubleshoot failed requests expose an outcome, while Resources and Learn more make the reader open a page to discover what it contains.

That rule applies to links, headings, and navigation labels. Use the same language across them where possible, then review the outline with the method in How to Write Task-Based Documentation Headings.

Test the homepage as a route inventory

The documentation homepage route audit turns the four route jobs into explicit fields a team can inspect. Its included fixture demonstrates the expected shape; it does not prove that the routes work for real readers.

python3 audit_homepage_routes.py example-homepage-routes.json

PASS
4 routes cover: exploration, first action, recovery, returning task

The script cannot prove that a reader will understand your labels. It can catch a more basic failure before the homepage ships: a route inventory that has forgotten the person who needs help after the happy path breaks.

Keep homepage scope separate from site organization

A homepage should route readers into the documentation system. It should not carry the full burden of URL migration, sidebar design, canonical ownership, or every product page.

For that wider work, use How to Organize Documentation That Has Drifted. Start the homepage audit with the page’s likely entry tasks, then make each chosen route lead to a page that actually completes its promise.

A good documentation homepage makes the next decision easier. If a reader still has to infer where to begin, which page owns their task, or where to recover from failure, the homepage is still acting like a card wall.

Built while writing this: the technical writing linter. Free, runs in the browser, no signup.

How to Write Task-Based Documentation Headings

Ninad Pathak — Sun, 16 Aug 2026 18:01:24 +0000

Originally published at https://ninadpathak.com/articles/how-to-write-task-based-documentation-headings/.

A heading should tell a scanning reader what the section contains. For a procedure, name the result or task.

For a concept, name the concept. For a failure, name the condition and the recovery path.

That is the whole rule. Task-based headings are not a mandate to put a verb in every heading.

An illustrative heading rewrite

<img src="/static/images/articles/how-to-write-task-based-documentation-headings/task-heading-anatomy.svg" width="1344" height="640" alt="An illustrative example rewrites the label Setup as Configure the client with an API key, identifying an action, object, and context.">

This example shows the difference between a topic label and a heading that states the work the section covers.

Match the heading to the section's job

A heading is a navigation label, a link target, and a promise about the content below it. Google's documentation style guide recommends descriptive, unique headings and task-based tutorial titles when a document primarily guides work.

Start by deciding what the section does. A procedure helps a reader reach a result, while an explanation answers a conceptual question.

A reference section identifies a field, object, or API behavior. A recovery section handles a known failure condition.

Section job	Generic label	Illustrative rewrite
Procedure	Setup	Create the project and install the CLI
Configuration	Configuration	Configure the client with an API key
Verification	Testing	Verify the endpoint accepts a signed test event
Recovery	Errors	Recover when signature verification fails
Explanation	Authentication	Token scopes and integration access
Reference	Options	Retry policy options for background jobs

The right-hand column is not a universal template. It shows how the heading can name the reader's task or the subject of the section instead of only naming a broad topic.

Write task headings for procedural sections

Use a task heading when the section tells the reader how to change a system or reach a checked result. The heading should usually make the outcome visible before the reader opens the section.

For example, Configure the client with an API key tells the reader what they will do and what it applies to. Configuration tells them only that the topic is configuration.

Add context when it changes the next action. An environment, prerequisite, failure condition, or target object belongs in the heading only if omitting it would make the task ambiguous.

Diátaxis describes how-to guides as goal-oriented directions. That is a useful check for documentation headings: prefer the reader's goal over a list of product controls.

For example, Delay retries after a rate-limit response explains the intended behavior. Set the retry_after field can be correct, but it makes the reader inspect the section before learning why that setting matters.

Use descriptive noun phrases for concepts and references

A verb makes sense when the reader is meant to act. It becomes awkward when the section exists to explain a concept or document a specific item.

Use a descriptive noun phrase for those sections. Token scopes and integration access gives the reader a clear subject and boundary. Overview does not.

The same rule applies to reference material. Webhook signature headers is a useful anchor because it names the object being documented. Details forces the reader to open the section to learn what those details are about.

A practical test is simple: can someone predict the section's subject from the heading alone? If the best answer is only "information about this topic," the label needs more work.

Keep heading hierarchy separate from heading wording

A precise heading can still be placed at the wrong level. The World Wide Web Consortium's headings tutorial explains that heading ranks communicate page structure and support in-page navigation for browsers and assistive technology.

Use one page title for the page's primary job. Use major section headings for the main tasks or concepts, then nest headings only for work that belongs within a parent section.

Do not choose a heading level because of its visual size. CSS can change how a heading looks.

Its level still changes the document outline and navigation structure.

Review the outline before the prose

Read the headings without the body copy. The review asks a narrower question than an editorial review: does the outline show the tasks, concepts, decisions, and recovery paths that the page promises to cover?

A procedural guide might have an outline like this:

Configure webhooks
Create the endpoint that receives events
Verify the endpoint accepts a signed test event
Recover when signature verification fails

This is an example outline, not a claim about every webhook guide. It works because each heading names a distinct part of the reader's path.

Compare it with labels such as Setup, Testing, and Errors. Those labels may be acceptable inside a tightly scoped interface, but they do not describe a task or subject by themselves.

Rewrite headings where the reader needs to choose a next step

Start with the headings that carry the most navigation work: the first action, prerequisites, verification, risky decisions, and recovery. Those sections are where a reader is most likely to scan for a specific answer.

Do not rewrite every heading into an imperative. A section that explains token scopes should say so.

A section that documents a request field should name that field. A section that guides a reader through a result should state the result.

For a full tutorial structure, see How to Write a Technical Tutorial That Actually Teaches. Before publishing, use the documentation review checklist to check the rendered outline, links, and navigation.

The useful standard is not "every heading starts with a verb." It is simpler: a reader should be able to tell why a section exists before they have to read it.

Accessibility Testing for Documentation: A Release Checklist

Ninad Pathak — Sat, 15 Aug 2026 18:01:49 +0000

Originally published at https://ninadpathak.com/articles/documentation-accessibility-checklist/.

Accessibility testing matters for documentation because a page can look finished and still leave a reader unable to complete its task. A bold heading, a link named “here,” or a screenshot holding the only success signal can turn setup instructions into a visual-only path.

Use this release checklist when you need to decide what to automate, what needs manual testing, and which failure should block a documentation deploy. I built and ran a documentation accessibility checker against a broken fixture and its repaired version so the human review can focus on the experience a parser cannot judge.

Accessibility testing checklist for a documentation release

Run this table against generated HTML and the rendered page. It separates repeatable source failures from the reader-path checks that only a person can complete.

Page element	What must survive	Quick check
Heading	Section structure	One page title, ordered heading levels, and no headings created only with visual styling
Code	Copyable instructions	Actual text, a declared language, a starting state, and an observable result near the command
Link	Destination and behavior	Link text names the destination and signals a download, new tab, or same-page jump when that behavior matters
Table	Relationships between values	A simple data table has headers, and layout is not built with table markup
Visual	Information beyond pixels	Meaningful images have useful alternatives, decorative images have empty alternatives, and complex visuals have nearby equivalent detail
Rendered page	Keyboard and zoom use	Focus remains visible, interactive controls work from a keyboard, and reflow does not hide the task

Download the documentation accessibility checker (.zip)

The script is deliberately narrow. It flags missing image alternatives, vague links, heading jumps, tables without header cells, and code elements without a language class.

Test documentation structure before visual styling

A documentation page needs structure that exists in the document model, not only in its theme. Google’s accessibility guidance recommends descriptive headings in a logical hierarchy, and Harvard’s structural guidance makes the consequence clear: assistive technologies can navigate structure only when the markup carries it.

Use headings to expose the task route

Keep one page title, then use heading levels to describe the task in dependency order. A level should never be selected for its font size because CSS can change appearance without breaking the document outline.

Read the headings without their paragraphs. A reader should be able to tell where to begin, what action follows, and where to verify success.

Keep lists and tables semantic

Use a list when several items belong together and a table only when readers need to compare consistent fields. A data table needs header cells, and a table used for visual layout invents a relationship that a screen reader will announce as data.

Microsoft State University’s checklist recommends simple tables with row and column headers. If the relationships cannot be stated clearly in headers, split the table or use prose and a list instead.

Test code and links on the reader’s path

A code block is part of the interface. The reader should be able to copy it, recognize its language, understand the required state, and confirm what a successful result looks like.

Put commands in text and name their language

Do not hide a command in a screenshot. Text can be copied, enlarged, searched, translated, and read by assistive technology, which is why Google’s guide advises against images of code and terminal output.

Use the code fence or HTML class that tells the renderer what language it contains. Put prerequisites and a success signal in nearby text rather than relying on an image caption.

# Run from a disposable test workspace.
python3 check_documentation_accessibility.py rendered-page.html

The expected result is a PASS line that names the file checked. A failure should name the structural issue so the author can repair it without guessing.

Give links a destination readers can choose

A link list is often how people scan a technical page. “Click here” becomes meaningless when it is separated from its paragraph, but “Read the documentation review checklist” tells the reader what they will get.

Name unusual behavior near the link when it changes the next move. A download, external application, same-page jump, or new tab should not be a surprise.

Test visual information has an equivalent text path

An alternative is not a caption copied into an alt attribute. It is the information someone needs when they cannot use the visual presentation.

Write alternatives for the visual’s job

Describe the result or decision the visual supports. If a screenshot proves that a request returned 200, say that, and keep the matching response detail in nearby text.

Open edX’s checklist draws the useful boundary: a meaningful graphic needs equivalent information, and a complex graph or diagram may need adjacent text or a data table. Decorative images should use an empty alternative so they do not add noise.

Check contrast and non-color cues together

A red error state must also say that the request failed. Color can reinforce a label, but it cannot be the only way to understand status, priority, or a comparison.

Use the WCAG 2.2 Quick Reference to inspect the relevant success criteria for text alternatives, information and relationships, contrast, keyboard operation, and link purpose. The standard is a reference point, not a replacement for trying the page’s real task.

Run automated checks before manual documentation testing

Automation can confirm markup patterns. It cannot tell whether focus is easy to find, whether a code sample wraps into unreadable fragments, or whether the page still makes sense at high zoom.

Automate repeatable source failures

I used the checker below on a fixture with one page title, ordered headings, a declared Bash block, descriptive link text, table headers, and an image alternative. The run passed after I restored those contracts.

Documentation accessibility checker on the repaired fixture

<img src="/static/images/articles/documentation-accessibility-checklist/checker-pass.png" alt="MacBook Air terminal window showing python3 check_documentation_accessibility.py rendered-page.html and a passing structural accessibility result">

The checker reports a passed structural check for the repaired fixture. It does not claim to test keyboard operation, color contrast, or screen-reader output.

Run it against generated HTML, not only the source Markdown. The rendered page is where plugins, templates, syntax highlighters, and image components can change the structure you intended.

Test the reader’s route with a keyboard and zoom

Tab through the page from the browser address bar. The current control should stay visible, links and controls should work without a pointer, and the order should match the reading order.

Then zoom until the page reflows and read the page with a screen reader when possible. The documentation review checklist covers the wider release review, including links, metadata, and the rendered frame.

Make accessibility testing a documentation release gate

Put this checklist beside the page template and run the checker in the same preview step that validates links and examples. The documentation style guide template can record the owner, release trigger, and manual-test boundary for rules that change with the product.

Accessibility gets cheaper when it is part of the authoring contract rather than a repair after launch. Start with one task page, preserve the semantics that explain its route, and let the rendered review show what the source alone cannot prove.

Documentation Style Guide Template for Developer Teams

Ninad Pathak — Fri, 14 Aug 2026 18:03:38 +0000

Originally published at https://ninadpathak.com/articles/documentation-style-guide-template/.

Documentation drifts when a feature changes and the name in the UI no longer matches the command in the guide. Tone alone cannot fix a decision that nobody can inspect or update.

I built the attached template to make decisions and their supporting evidence visible. It also records when a release change should trigger review.

Download the documentation style guide template

Keep the file beside the product source. When a feature is renamed or a command changes, review the matching row in the same pull request instead of relying on someone to remember a separate editorial process.

The first useful use is one guide that changes often. Fill its bracketed fields with product facts, run the checker, and let the next release show which parts of the template need more detail.

Define terminology that readers can verify

A terminology entry needs an approved name, a short definition, an owner, and a date when someone last checked it. That turns a naming dispute into a question a reviewer can settle against the product.

Google’s word list is a useful reference because it records preferred wording and usage decisions. Your product needs the same discipline for names that exist only in its permissions model, API, migration flow, or interface.

When a term appears	What the guide should record	What the reviewer can check
A new product capability	Approved name and definition	The same name appears in UI, docs, and release notes
A renamed concept	Deprecated name and migration reason	Readers can connect the old term to the current path
A role or permission	Exact role name and responsibility	The described access matches the released product

Keep a deprecated term only when readers can still encounter it. An error message or compatibility field may need it, but an old marketing name does not need permanent search weight.

Match page shape to the reader task

Each page form needs a completion signal that tells the reader when the task is complete.

A tutorial should leave you with a working response or screen state. A reference should answer a stable question.

Google’s UI guidance recommends writing instructions around the result the reader needs. Use an exact label when the control matters, then give enough context for a reader to recognize the correct screen.

One rule carries a lot of weight for a small team: one page owns one reader question. Link out when a prerequisite, field definition, or recovery path belongs somewhere else.

The technical documentation template shows how page jobs become a small site structure. The documentation organization guide helps when existing pages compete for the same question.

Record the evidence behind code examples

A code rule that says “use fenced blocks” leaves out the part that matters. Readers need the runtime, package version, starting state, command, and observable result that made the snippet safe to copy.

The template places a compact environment table before the command so a reviewer can see what the example depends on. That catches the hidden service, credential, or local file that turns a plausible snippet into a support ticket.

# Run from: [working directory]
# Requires: [access, environment variables, or local service]
[copyable command]

Google’s code-syntax guidance covers the presentation of code and command syntax. The local rule here is narrower: when product behavior can change, place the verification source and failure boundary beside the example.

I ran the included validator against the downloadable template in a fresh Python 3.13.5 environment. It confirmed the required sections, evidence markers, and editable cells that a team must replace with product facts.

The checker cannot tell whether an API response still matches production or whether a screenshot shows the current interface. It fails when someone removes the fields that make those claims inspectable.

Keep UI references tied to a released interface

UI documentation fails when a writer describes a control from memory. The prose can be polished and still send someone to a label that was renamed, moved, or placed behind a permission.

The template pairs visible wording with a release URL, build, or screenshot and a verification date. That gives the product owner a narrow claim to confirm during release review.

GitLab’s documentation style guide and Microsoft’s style guide are useful references for a maintained editorial system. Neither can decide whether your “Create environment” button became “New environment,” so keep a local source of truth for the product your readers use.

The documentation review checklist covers links, accessibility, metadata, and rendered behavior. Use this template earlier, before the team decides what a reference means.

Give each rule an owner and an update trigger

A style guide can become bureaucracy. That happens when it turns into a catalog of preferences that does not prevent a reader mistake or map to a product change.

Keep rules that stop readers from choosing the wrong term, running an incomplete command, following a stale interface path, or missing the page that owns a question. Each row needs an owner and an update trigger such as a renamed feature, revised permission, changed response shape, or a support issue that exposed an ambiguous page.

Download the template, fill it against a frequently edited guide, and run the included checker before asking the rest of the team to adopt it.

Internal vs. External Documentation: What Belongs Where

Ninad Pathak — Thu, 13 Aug 2026 18:01:37 +0000

Originally published at https://ninadpathak.com/articles/internal-vs-external-documentation/.

Internal documentation helps your team operate the system. External documentation helps customers, partners, and public developers use the supported product.

When both tasks exist, publish a public task page and keep a separate private operating record. Classify each subject as internal, external, or split.

Internal vs. external documentation: choose by reader task

Google's technical writing guidance on audience defines an audience by the knowledge and skills it needs for a task. Use that task, not a person's job title, to decide where a page belongs.

Ask four questions:

Does someone outside the organization need this information to evaluate, use, integrate with, administer, or recover the product?
Does the subject contain credentials, private topology, unpublished plans, exploit detail, personnel information, or candid incident analysis?
Does an internal operator need implementation context that an external reader does not?
Who owns the source of truth, and which product or process change makes it stale?

<source>
<img src="/static/images/articles/internal-vs-external-documentation/documentation-placement-flowchart.svg" width="672" height="472" alt="Documentation placement flowchart. If no external reader needs the information, keep it internal when an operator needs it or review whether the page has a task. If an external reader needs it, split public and private context when both remain necessary; otherwise publish it externally.">

Each path ends in internal, review, split, or external documentation without crossing connector lines.

Internal vs. external documentation comparison

Signal	Internal documentation	External documentation	Split documentation
Primary reader	Employee, contractor, or approved operator	Customer, partner, public developer, or product administrator	Both groups
Reader task	Build, deploy, operate, support, decide, or change the system	Evaluate, start, integrate, configure, use, migrate, or recover	Complete an external task while preserving private operating context
Typical detail	Architecture decisions, private dependencies, internal commands, staffing, controls, and candid analysis	Supported behavior, prerequisites, procedures, examples, limits, errors, and recovery	Public contract on one side, implementation and sensitive context on the other
Access	Identity and role based	Public or customer authenticated	Separate access and separate documents
Update trigger	Process, topology, control, tooling, or ownership change	Product contract, interface, workflow, or release change	Either side changes

IBM's code documentation overview makes the same practical distinction. Coding standards and development-environment setup serve internal work, while public API reference, integration notes, configuration, and README files can serve external work.

What belongs in internal documentation

Architecture decisions and system design

Keep architecture decision records, private topology, capacity assumptions, data classifications, vendor constraints, and unreleased plans with the team that operates them. A public architecture page should explain only the integration model, trust boundary, data flow, or deployment responsibility that changes a customer's decision.

Runbooks and internal recovery procedures

Keep privileged commands, escalation paths, rollback criteria, dashboards, and candid failure analysis behind the appropriate access boundary. External troubleshooting should start from an observable symptom, give a safe recovery path, and state when to contact support.

Employee onboarding and working agreements

Local access, internal repositories, approval paths, team ownership, coding standards, and deployment responsibilities belong in contributor onboarding. Atlassian's internal documentation guidance treats this material as living team knowledge, which means it still needs ownership and review.

What belongs in external documentation

Product scope and getting started

Publish prerequisites, the supported first action, expected result, and the next useful page when an outside reader needs them to start. A documented happy path should not require a support conversation to complete.

Public interfaces and product contracts

Publish API endpoints, SDK methods, command flags, configuration fields, error behavior, limits, compatibility promises, and supported authentication flows. The reader needs the request shape, authorization requirement, response, failure behavior, and relevant limits, not the service graph that fulfills the request.

Releases, migrations, and customer recovery

Publish release notes, migration guides, deprecation notices, and troubleshooting when product behavior changes or a supported task can fail. The page must answer whether the reader is affected, what to change, when to change it, and how to confirm recovery.

When to split internal and external documentation

A split is not a redacted internal page. It is a public document with a customer task and a private document with the operating detail required to maintain that public promise.

Shared subject	Internal documentation	External documentation
Production incident	Timeline, contributing conditions, response decisions, corrective work, and private evidence	Customer impact, affected period, restored state, customer action, and follow-up commitment
System architecture	Decisions, private topology, controls, dependencies, and operational constraints	Supported deployment model, integration boundary, data flow, and customer responsibility
Authentication	Key handling, abuse controls, rotation operations, and internal escalation	Authentication flow, scopes, supported credentials, errors, rotation task, and recovery
Product release	Launch plan, rollout criteria, internal risks, and rollback decision	Shipped behavior, impact, required action, compatibility, and migration path

Link the private source to the public contract it maintains. Give each page its own owner and update trigger, because a supported authentication flow can change without changing the internal key-rotation runbook.

Documentation placement audit template

Start with an inventory. Record whether an external reader has a task, whether private context exists, whether an internal operator has a separate task, who owns the page, and what makes it stale.

I encoded that inventory in a small documentation placement audit and ran it against an eight-artifact sample manifest. The run classified three artifacts as internal, three as external, and two as split.

python3 documentation_placement_audit.py

AUDIT PASSED: 8 artifacts, internal=3, external=3, split=2, review=0

Inspect the generated CSV report before adapting the fields to your own inventory. The script exposes mixed audiences and missing ownership, but a security or legal reviewer still decides what the organization may publish.

Documentation ownership and update triggers

Placement	Primary owner	Useful update triggers	Completion signal
Internal	Team closest to the system or process	Topology, workflow, control, tooling, incident, or ownership change	An operator can complete the internal job safely
External	Product documentation, developer experience, or product team	Interface, behavior, prerequisite, limit, error, version, or support-pattern change	An outside reader can complete the promised task
Split	Named owner for each side, with one contract between them	Any change that makes the public promise and private operation disagree	Both pages agree on supported behavior without sharing private context

GitLab's documentation style guide treats product documentation as a maintained source of truth for implementation, use, and troubleshooting. Apply the same maintenance discipline to private operational material.

Start with the external task. If the answer also requires private operating context, create paired documents instead of widening one page until it serves neither reader well.

Use the types of technical documentation to choose the artifact each reader needs. If duplicate pages and navigation drift already hide the canonical answer, organize the documentation site before adding more pages.

Types of Technical Documentation: 8 Essential Types, Plus Agent Instructions

Ninad Pathak — Wed, 12 Aug 2026 18:02:05 +0000

Originally published at https://ninadpathak.com/articles/types-of-technical-documentation/.

Technical documentation is not one thing. It is the set of documents that help someone use a product, understand a system, operate it safely, or change it without losing important context.

The three audiences for technical documentation

The most useful classification separates technical documentation by the person who needs it. ClickHelp makes a similar distinction between process documents and user documents, while Squarespace Engineering frames documentation around reader behavior, patience, experience, and goal.

That gives you three useful groups. User-facing documents help customers or developers adopt a product.

Process documents help the people building and operating it. Agent instructions give coding agents repository-specific context that would be distracting or irrelevant in a human-facing guide.

User-facing documentation helps someone use the product

These are the documents a customer, developer, administrator, or new user opens when they want to get started, complete a task, find a precise answer, or fix a failure.

1. Getting-started guides and quickstarts

A getting-started guide takes someone from no working setup to a first result. It should name prerequisites, show the smallest supported path, and make success visible.

React’s Learn section moves from an introduction to concepts and hands-on learning without treating a new reader as if they already know the framework. A quickstart is not a full manual.

Its job is to establish confidence and give the reader a sensible next page.

2. Tutorials

A tutorial teaches a capability through a guided sequence. It can combine several tasks because the reader is learning a skill, not only changing one setting.

Squarespace Engineering distinguishes tutorials from how-to guides on that point. A tutorial demonstrates a use case or concept, while a how-to guide completes one bounded task.

Keep checkpoints in the path so the reader can see whether they are still on track.

3. How-to guides

A how-to guide answers a specific operational question such as “rotate an API key,” “configure single sign-on,” or “add a webhook endpoint.” The reader already understands enough of the product to name the job.

A strong guide states the starting condition, required access, procedure, success state, and recovery boundary. It does not repeat the product introduction or explain every adjacent feature.

4. Reference documentation

Reference is where exact details live. API endpoints, request fields, SDK methods, configuration values, defaults, limits, return types, and error conditions belong here because readers need information they can scan and depend on.

Stripe’s API reference shows the central contract clearly. A reader can move from an object to its endpoints and fields without reading a tutorial first.

Reference can include examples, but the examples should clarify the contract rather than turn the page into a learning path.

5. Troubleshooting guides

Troubleshooting starts with a symptom, not a feature. The reader has already hit a failure and needs a way to identify the cause, recover safely, or know when to escalate.

Kubernetes’ troubleshooting documentation organizes debugging work around the problem a user must diagnose. Good troubleshooting pages include the observable symptom, a diagnostic check, likely causes, a safe fix, and the point where guessing becomes risky.

6. Release notes and migration guides

Release notes tell people what changed. Migration guides tell them what they need to do about that change.

Treat those as related but different documents. A release note can announce a deprecated API version or a changed permission model.

A migration guide should provide the affected starting state, replacement path, compatibility boundary, and a way to confirm completion.

Process documentation helps a team build and operate the system

Product documentation is only one part of technical documentation. Teams also need durable records that explain why a system exists in its current form and how to maintain it.

Use the internal vs. external documentation decision to keep private operating context separate from the public task or contract.

7. Architecture and design documents

Architecture documents describe the system’s components, boundaries, data flows, dependencies, and important decisions. A design document is often narrower, explaining a proposed change before implementation begins.

These documents should answer questions that source code cannot answer quickly. They should make system boundaries and important decisions inspectable.

For example, explain why a queue was selected over a synchronous call, which service owns a data set, and what assumptions make a deployment safe. A diagram can help, but it does not replace those decisions and constraints.

8. Runbooks, onboarding guides, test plans, and standards

Some process documents exist because somebody must perform the same work safely more than once. Runbooks describe routine or incident procedures.

Onboarding guides give a new teammate the systems, access, and conventions they need. Test plans name the scope, method, risks, and expected outcome of verification work.

Style guides and contribution guides belong here too. They turn unwritten conventions into something a contributor can inspect before they create avoidable review work.

Tango’s collection of technical document types is useful for this broader view. It includes product manuals, quick-reference guides, requirements, project plans, roadmaps, test plans, release notes, and style guides rather than reducing technical documentation to API pages and tutorials.

The newer type: instructions for coding agents

A repository can now have another reader that needs documentation: a coding agent.

AGENTS.md is an open Markdown convention for repository instructions aimed at coding agents. Its purpose is not to replace a README.

A README still helps people understand a project, install it, contribute to it, and find the public interface. An AGENTS.md file can hold the build commands, test commands, code conventions, security concerns, deployment details, and local rules that an agent needs when changing the repository.

This is a useful addition because human contributors and coding agents need overlapping but different context. A human may need a project overview and contribution path.

An agent may need the exact command sequence, test scope, nearest-file instruction rule, and prohibited changes before it edits code.

Keep the boundary visible. Do not hide human onboarding inside an agent file, and do not expect a long README to provide the focused instruction an agent needs during an edit.

If both audiences work in the repository, maintain both documents and link between them where the information overlaps.

Build documentation from the work people need to finish

You do not need every document type on launch day. Start by listing the moments where users and operators need an answer that cannot safely remain in chat history, a ticket, or one person’s memory.

For a public API, that first package may include a quickstart, API reference, authentication guide, error guide, and release notes. For an internal service, it may start with an architecture document, onboarding guide, deployment runbook, and incident procedure.

For an agent-enabled repository, add AGENTS.md when the agent needs instructions that should remain close to the code.

Then give each document a clear owner and update trigger. An API schema change should trigger reference review.

A revised deployment flow should trigger runbook review. A recurring support issue should trigger troubleshooting work.

A changed build command should trigger README and agent-instruction review.

I reviewed the ranking pages for this query, including ClickHelp, Tango, and Squarespace Engineering, alongside the AGENTS.md guidance. The useful conclusion is not that every team needs the same list.

Documentation becomes easier to maintain when each type has a named audience, a distinct job, and a change that tells its owner when to revisit it.

Use the technical documentation template to turn that inventory into a working plan. Then use the technical documentation best practices to test whether each page helps someone complete the job it promises.

What Is Technical Documentation, and What Should It Include?

Ninad Pathak — Tue, 11 Aug 2026 18:02:28 +0000

Originally published at https://ninadpathak.com/articles/what-is-technical-documentation-and-what-should-it-include/.

Technical documentation is the material that helps someone understand, use, integrate with, or safely operate a system. It works when a reader can take the next step without guessing.

Think of it as a route through a product. A tutorial gets someone moving, reference answers an exact question, explanation gives a decision context, and troubleshooting helps when the route breaks.

What technical documentation should include

Start with the reader task, not a list of page types. A developer evaluating a product needs different information from someone sending a first API request or investigating an error.

Reader task	Document that owns it	What must be visible	What shows it is enough
Decide whether the product fits	Orientation or README	Scope, non-scope, supported use cases, and a starting link	The reader can name the first relevant path
Complete a first integration	Quickstart or tutorial	Prerequisites, one supported path, expected output, and a failure link	The reader reaches a recognizable result
Understand a system choice	Explanation	Terms, model, constraints, and links to task pages	The reader can explain the choice before implementing it
Change an existing behavior	How-to guide	Starting state, procedure, success state, and recovery boundary	The reader can perform the change safely
Look up an exact question	Reference	Names, types, defaults, constraints, and exceptions	The reader can find the answer without inference
Diagnose a failure	Troubleshooting	Symptom, diagnostic check, cause, recovery, and escalation boundary	The reader can choose the next safe action
Respond to a product change	Release note or migration guide	Impact, required action, version or date, and a migration path	The reader can decide whether action is required

The idea is, one page should not teach a beginner, document every field, explain the architecture, and debug production failures. Split those jobs so each page can answer its question completely.

The Diátaxis framework separates tutorials, how-to guides, reference, and explanation for the same reason. The names help, but the reader task decides whether a page belongs in one category or another.

Build the smallest package that lets someone succeed

A small team does not need seven finished document types before launch. It needs enough material for the first reader to understand the product, finish one supported task, and locate the stable details or recovery guidance that task depends on.

For an API, that often means an orientation page, a quickstart, and reference for the endpoint or SDK used in that quickstart. Add troubleshooting when a failed setup has a meaningful diagnostic path, then add release material when product changes can affect an existing integration.

For a CLI, orientation should explain the tool’s job and supported environments. The quickstart should produce one visible command result, while reference owns commands, flags, exit behavior, and configuration.

An internal platform may need a different starting package. Access, a supported setup path, ownership, and the operating rules that change a team’s next action can matter before a public-style product portal.

Use the internal vs. external documentation decision when the same subject needs both private operating context and a public task-focused treatment.

Google’s technical writing guidance recommends defining scope, non-scope, and audience before expanding a draft. That decision keeps a page from collecting unrelated jobs as it grows.

Give each document a boundary

An orientation page helps a reader decide where to begin. It should answer what the product does, who it is for, what it does not cover, and where the first supported task starts.

A quickstart proves one supported path. It should link to reference when exact options matter and to troubleshooting when a failure would block the first result.

An explanation page gives a model for a design choice. It should make the next task easier without forcing the reader to learn every concept before they can do useful work.

A how-to guide changes one behavior from a known starting state. Keep details that remain stable across many tasks in reference, and keep recurring failures in troubleshooting.

Reference owns the public API surface. Google’s API reference guidance calls out methods, parameters, returns, and exceptions because implementation depends on exact behavior rather than narrative approximation.

Troubleshooting starts from a recognizable symptom and gives a diagnostic check, likely cause, safe recovery, and escalation boundary. A generic support link cannot tell someone whether a retry is safe.

Release notes explain changed behavior and required action. They should link to the canonical guide or migration page instead of repeating every instruction.

Make coverage inspectable before writing prose

A document list can hide missing ownership. I ran a small documentation deliverables manifest for a webhook API example so every planned page has one reader task, success signal, owner, review trigger, and deferral condition.

.venv/bin/python static/templates/validate_documentation_deliverables.py

The validator passed with seven owned reader tasks. That result does not tell you whether every paragraph is good, but it does expose a missing task owner before a repository fills with overlapping pages.

Documentation deliverables manifest validation

<img src="/static/images/articles/what-is-technical-documentation-and-what-should-it-include/documentation-deliverables-manifest.png?v=0c2f9fe6" alt="Terminal output showing a documentation deliverables manifest with seven owned reader tasks passed validation">

The validator checks each planned deliverable for a reader task, completion signal, owner, update trigger, and deferral condition.

Use this kind of check before writing a documentation site from scratch. It is planning evidence, not a replacement for task testing, source checks, or editorial review.

Assign an owner and an update trigger

A review date alone does not keep documentation current. Give each deliverable an owner and a product change that requires review, such as a schema change, permission change, new release behavior, support issue, or incident.

GitLab’s documentation guidance treats documentation as maintained product material for configuring, using, and troubleshooting a system. Update the page when product behavior makes its existing instructions unsafe or incomplete.

A useful review trigger connects the document to the change that can invalidate it. A schema change should prompt reference review, a revised onboarding flow should prompt quickstart review, and a recurring failure should prompt troubleshooting work.

Use a technical documentation template when you are ready to turn these decisions into a repository. Then test whether a page helps someone finish a task before calling it complete.

Use the documentation review checklist before publication. If duplicate or stale answers are the problem, start by organizing documentation that has drifted instead of adding another page.

Technical Documentation Best Practices, Tested on Real Developer Docs

Ninad Pathak — Mon, 10 Aug 2026 18:03:04 +0000

Originally published at https://ninadpathak.com/articles/technical-documentation-best-practices-tested-real-developer-docs/.

A documentation page can be accurate and still fail the moment a reader leaves the happy path. The useful test is smaller: can someone complete one task, recognize the result, and recover from the failure most likely to interrupt it?

The review uses FastAPI’s error-handling guide, Stripe’s idempotency reference, and GitHub’s REST API rate-limit guide. A live source check returned 200 for all three pages and confirmed the terms this review discusses: HTTPException, Idempotency-Key, and x-ratelimit-remaining.

Download the documentation task review card and use it on a single important page before you expand a docs section. It turns a vague request for “better docs” into evidence a writer, engineer, and maintainer can inspect together.

Technical documentation best practices that help readers finish a task

Start with a task and a success state

Readers do not arrive to learn an internal content model. They arrive with a job: return a useful error, retry a request safely, or understand why a request stopped working.

FastAPI’s guide starts with an error response before it introduces HTTPException. Its useful choice is the connection between condition, HTTP status, and response body, which lets the reader identify the state they created.

A documentation page should make one finish line visible:

Page type	Reader task	What proves completion
Tutorial	Complete a first useful action	A command, response, or screen state
How-to	Change one system behavior	The input and expected result
Reference	Resolve a stable question	A field, default, constraint, or type
Troubleshooting	Recover from a known failure	Symptom, diagnostic, cause, and recovery

A reference page can stay compact instead of carrying a full end-to-end scenario. It still needs to identify the question it owns and the boundary that changes the answer.

Put recovery next to the action that can fail

The most expensive documentation gap is often distance. A reader sees a happy-path request in one guide, hits a timeout, and has to search a separate FAQ to learn whether retrying will duplicate work.

Stripe’s idempotency reference makes retry behavior part of the request contract. The relevant reader decision is not simply “add a header.”

The decision is whether the same operation can be retried safely, what identifies that operation, and when changed parameters break the assumption.

Use the same structure for any action with a meaningful failure mode:

Show the expected success state.
Name the response, error, or condition that signals failure.
Explain the repair, retry, or backoff decision.
State the condition that makes that repair unsafe.

A common objection is that this makes a quickstart longer. That is true for a simple, reversible task with an obvious error.

Once permissions, retries, asynchronous work, or quotas can change the outcome, leaving recovery elsewhere is not brevity. It is an undocumented implementation decision.

Make limits observable before they become incidents

A warning that an API “may throttle traffic” cannot help a client decide whether to queue work, slow down, or investigate configuration. The page needs a signal the client can inspect.

GitHub’s rate-limit documentation distinguishes rate-limit behavior and exposes headers such as x-ratelimit-remaining. That gives a developer an observable state to log or automate instead of a generic support symptom.

For each limit, answer these questions in the same place:

What resource is limited?
Which header, field, dashboard value, or response shows remaining capacity?
What state marks exhaustion?
What should the client do next?
When should the client stop retrying or escalate?

Use the review card’s limit table to make this operational. If the writer cannot fill the signal and recovery columns, the documentation has not yet given the reader enough control.

Give every reader question one owner

Documentation drifts when tutorials, reference pages, release notes, and support articles all explain the same behavior differently. More navigation does not fix that conflict.

Assign one page to own the task, then link outward for prerequisites, stable parameter detail, and deeper recovery. The documentation organization guide explains how to split those page roles, while the documentation review checklist covers the release checks that follow.

The owner should also know what invalidates the page: a changed permission, renamed control, new response shape, revised quota, or support issue that reveals an absent recovery path. A review date alone cannot keep documentation current.

Use the review card before you publish

The card is deliberately small. It asks for a reader, starting state, task, success state, risky action, failure signal, recovery boundary, limit signal, and page owner.

Run it on the highest-risk page first, not every page at once. A payment request, authentication guide, migration path, or quota-sensitive endpoint is a better starting point than a low-stakes glossary entry.

The point is not to make documentation longer. It is to stop forcing a reader to infer the state that determines whether the next action is safe.

Download the review card, fill it against one rendered page, and turn the unanswered cells into the next documentation change.

Technical Documentation Template: Build Product Docs With a Tested Structure

Ninad Pathak — Sun, 09 Aug 2026 18:02:39 +0000

Originally published at https://ninadpathak.com/articles/technical-documentation-template/.

Creating documentation often forces several decisions at once: where readers begin, how they complete the first task, where exact details belong, and how they recover when a step fails. A template reduces that first pass to a structure you can inspect and adapt.

I built this template to solve a narrow problem: an empty documentation repository leaves every contributor to invent navigation, page responsibilities, and release checks again. It provides five focused pages, a local validator, and a strict build path so the structure is useful before the product-specific writing begins.

Download the technical documentation template

Download the template

Unpack the archive, then replace the placeholders with evidence from your product. The remaining sections show what belongs in each page and how to verify the result.

What a technical documentation template should include

A technical documentation template is a reusable starting structure for product or engineering documentation. It should tell a contributor where a reader begins, where they complete a task, where they look up stable details, and where they recover from a known failure.

A table of contents alone cannot do that work. It can label a page “Getting started” without establishing prerequisites, a tested command, an expected result, or a recovery path.

The starter contains five pages because they create a complete first route without pretending every product needs the same collection.

Page	Reader job	Evidence to add before publishing
index.md	Choose the first useful task	A direct route to the right starting page
getting-started.md	Complete first setup	Prerequisites, a tested command, expected output
guides/send-a-request.md	Perform one bounded task	A full request and response or observable state
reference/configuration.md	Look up stable details	Names, types, defaults, and constraints
troubleshooting.md	Recover from a known failure	Symptom, diagnostic check, cause, and recovery

Tutorials, how-to guides, reference, and explanation serve different reader needs. This template starts with a smaller product-docs system, then leaves room to add explanation when a concept needs more than instructions.

The files included in the template

The archive contains Markdown source, MkDocs configuration, a validator, and a GitHub Actions deployment workflow.

technical-documentation-template/
├── docs/
│   ├── index.md
│   ├── getting-started.md
│   ├── guides/send-a-request.md
│   ├── reference/configuration.md
│   └── troubleshooting.md
├── scripts/validate_docs.py
├── .github/workflows/deploy.yml
├── mkdocs.yml
└── requirements.txt

This layout keeps navigation, source, validation, and deployment close together. The documentation is not just a folder of Markdown files.

It is a small publishing system with inputs and checks.

MkDocs uses the same basic split: a configuration file defines the site, a docs directory contains the source, and a build produces static output. Keeping those roles separate makes a broken link or missing navigation target easier to locate.

Turn placeholders into a tested first task

Start with the smallest action that proves your product is usable. For an API, that could be an authenticated request returning a known response.

For a CLI, it could be installation followed by one safe command. For an internal service, it might be a local development setup that reaches a health endpoint.

Write the getting-started page around that outcome. State what the reader needs before beginning, give the exact action, show the expected state, and link to the next task.

A webhook product provides a concrete example. A vague template might say, “Configure a webhook endpoint.”

A useful task page instead identifies the event, endpoint URL, signing-secret requirement, request body, successful response, and how to inspect a failed delivery. Each item answers a different question the reader encounters while completing the task.

Do not move every option into the getting-started page. Put stable names, types, defaults, and constraints in reference.

Stripe’s API reference is useful to study because readers can move from an object to endpoints and fields without having to follow a tutorial first.

Give each page one owner and one update trigger

A template stays useful when placeholder text is replaced with product evidence and maintained as the product changes.

Give every page an owner and name the change that requires review. An API schema change should trigger reference review.

A revised onboarding path should trigger getting-started review. A recurring support issue should create or update troubleshooting guidance.

This rule is more useful than adding pages by habit. A page belongs in the documentation set when it owns a reader decision that would otherwise make another page harder to scan, update, or verify.

Use the documentation organization guide when existing pages overlap. Use the technical documentation types guide when you need to decide whether the missing page is a tutorial, how-to guide, reference page, explanation, or an operational document.

Validate the template before you publish it

The starter validator checks that every navigation target exists, each Markdown page has one H1, and local Markdown links resolve.

python scripts/validate_docs.py
mkdocs build --strict

The validation is deliberately narrow. It cannot prove that a live API endpoint works, a permission is correct, or a screenshot matches the current interface.

Those claims still need product-level checks.

Template validation and strict build receipt

<img src="/static/images/articles/technical-documentation-template/template-build-receipt.png" alt="Terminal receipt showing five navigation targets, five Markdown pages, one H1 per page, resolvable local links, a strict MkDocs build, and generated index and sitemap files">

The starter passed its repository checks and produced a static site in a fresh environment.

I kept the validator beside the source because navigation defects are cheaper to catch before deployment. The documentation review checklist adds a reader-facing review of links, visuals, accessibility, and the rendered page.

Publish the generated site, not your working files

The included workflow installs pinned requirements, runs the validator, builds the site directory with strict checks, uploads that directory as the Pages artifact, and deploys it. Enable GitHub Actions as the publishing source before expecting a public site.

GitHub Pages documentation confirms that static-site generators can publish through a custom Actions workflow. Verify the public URL after the workflow finishes rather than treating a green build as a public release.

- run: python scripts/validate_docs.py
- run: mkdocs build --strict
- uses: actions/upload-pages-artifact@v3
  with:
    path: site

Do not put production credentials, private examples, or customer data in the repository. Pages content is public on the internet even when a plan permits a private repository.

Add pages when a reader need appears

Begin with one tested path. Add reference when users need stable details without reading a guide.

Add troubleshooting when a failure has a recognizable symptom and recovery. Add explanation when readers need to understand a design choice before they can apply it safely.

That is how the template stays smaller than the product while still growing with it. The archive gives you the first structure and verification loop.

Product evidence decides what belongs in it next.

Technical SEO Checklist for Documentation Sites

Ninad Pathak — Sun, 09 Aug 2026 16:56:46 +0000

Originally published at https://ninadpathak.com/articles/seo-for-technical-documentation/.

I built the audit for this guide around two pages: a working Cloudflare documentation guide and a deliberately broken local fixture. The contrast was useful because both pages had visible content, yet only one gave a crawler and a developer a dependable path through the task.

A page succeeds when search engines can discover and interpret it, the right developer recognizes the task from the result, and the instructions carry that person to a working state. That is what this audit checks through search intent, discovery, crawling, indexing, canonicalization, page quality, performance, and measurement.

Technical SEO audit checklist: what to check

Area	Question	Blocking evidence
Search intent	Does this page own one developer task?	Another page already answers the same query better
Discovery	Can a crawler reach the URL through links?	No crawlable internal link from an indexable page
Crawling	Can the server return the page and its required resources?	Blocked URL, redirect loop, repeated `5xx`, inaccessible HTML
Indexing	Is the page eligible for search?	`noindex`, soft 404, duplicate without a clear canonical
Canonicalization	Do all URL signals identify the same page?	Canonical, sitemap, redirect, and internal links disagree
Page quality	Can the reader identify and complete the task?	Generic title, stale version, missing prerequisites, broken example
Measurement	Can the team see what happened after release?	No baseline, change annotation, or page owner

Step-by-step SEO audit for documentation sites

Work through these eight checks in order. Fix the first blocking failure before moving to the next check.

1. Search intent and page ownership

Make page ownership the first thing in your audit because developer searches usually contain a task, command, error, product, parameter, or version. The page that owns the query should name that task and make the successful state easy to recognize.

Search	Page that should own it	Successful outcome
`cloudflare workers deploy`	Deployment guide	A Worker reaches a live URL
`stripe 401 invalid api key`	Authentication troubleshooting page	The request succeeds after the cause is fixed
`kubectl logs flags`	Command reference	The reader chooses and runs the correct flag
`oauth refresh token expiry`	Concept plus implementation guide	The application renews access safely
`migrate sdk v2 to v3`	Versioned migration guide	The application runs on the supported version

If two pages complete the same task, compare the documentation, marketing site, support center, changelog, and older versions before writing anything new. One page should become the canonical owner, with useful material from the weaker page moved into it before the duplicate is redirected or demoted.

The documentation organization guide covers that consolidation work in detail.

2. Internal links and XML sitemaps

Google's SEO Starter Guide identifies links as a primary way crawlers discover pages. Trace every important documentation URL back to a relevant hub, guide, or sibling page instead of treating its XML sitemap entry as the entire discovery strategy.

The internal route has to make sense for a person too. A useful link carries the reader toward a prerequisite, a deeper explanation, or the next task rather than existing only because an audit wanted another inbound link.

Crawlable internal links

Google's crawlable-link guidance recommends an <a> element with an href that resolves to a web address. Look for that ordinary HTML before trusting a navigation path, since JavaScript click handlers and empty anchors are less dependable for crawling and keyboard navigation.

<a href="/docs/webhooks/verify-signatures/">
  Verify webhook signatures
</a>

The anchor should still identify the destination when someone reads it without the surrounding sentence. “Verify webhook signatures” carries the task on its own, while “Read more” asks both the reader and the crawler to infer it.

XML sitemap checks

Treat the sitemap as a record of the URLs the site actually wants search engines to consider. Google's sitemap guidance recommends fully qualified canonical URLs, which makes the following signals straightforward to compare:

The sitemap returns 200 and valid XML.
Every URL uses the preferred host and protocol.
Redirects, 404 pages, parameter variants, and noncanonical duplicates are absent.
<lastmod> changes only after a meaningful page update.
The sitemap is declared in robots.txt or submitted through Search Console.

Google ignores <priority> and <changefreq>, so those fields do not need release time.

3. Crawling, rendering, and indexing

The browser can make a broken page look healthy after JavaScript has run. Read the server response before reviewing the layout because it shows whether the content, links, and canonical metadata exist without asking a renderer to repair the page.

HTTP response and rendered HTML

For the Cloudflare audit, I started with the final URL and headers:

curl --silent --show-error --location \
  --dump-header headers.txt \
  --output page.html \
  https://docs.example.com/api/authentication/

The response reveals the status code, content type, redirect chain, X-Robots-Tag, and cache behavior before presentation enters the picture. It also exposes branded error pages that return 200 and risk being treated as soft 404s.

Open the page in a clean browser context and compare the rendered result with the source. The stage is complete when the task content, title, headings, navigation, code, links, and canonical appear without a logged-in state or extra interaction.

Google's JavaScript SEO guidance explains how rendering affects indexing. Search Console URL Inspection shows Google's indexed view and live-test result.

`robots.txt` and `noindex`

robots.txt controls crawling, while a page-level or header-level noindex controls indexing. The distinction matters because Google still has to crawl a page before it can see the indexing directive.

Resolve duplicates through redirects or canonical signals rather than hiding them in robots.txt. A noindex directive fits pages that should remain accessible but should not appear in search.

4. Canonical URLs and documentation versions

Redirects and rel="canonical" are strong canonicalization signals. Sitemap inclusion is weaker, so compare the signals together because disagreement usually reveals that templates, navigation, and deployment rules are describing different preferred URLs.

Include:

Final response URL
Source rel="canonical"
XML sitemap URL
Internal-link destinations
hreflang URLs when present
Structured-data URL
Open Graph URL

The preferred page needs an absolute self-referencing canonical, with every supporting signal pointing to it. Google's canonicalization guidance also recommends linking internally to that preferred URL.

<link
  rel="canonical"
  href="https://docs.example.com/api/authentication/"
>

Versioned documentation is where policy becomes more important than a universal rule. Choose among three patterns based on whether the old instructions can still produce a valid result:

Current version only: Redirect retired task pages when the old instructions are no longer useful.
Multiple supported versions: Give each version a distinct URL, visible label, navigation path, and self-canonical.
Historical versions: Keep them accessible, then decide whether they should remain indexable based on support and search demand.

If the instructions materially differ, keep the older page distinct rather than canonicalizing it to the current version. The pages are not interchangeable when following the wrong one can break an integration, and the URL policy should preserve that distinction.

5. Page titles, headings, and task content

Labels such as “Overview,” “Configuration,” and “Usage” lose meaning when they leave their section. A useful label should still identify the task in a search result, browser tab, documentation tree, or copied URL.

The Google title-link guidance recommends a distinct, concise, accurate <title>. Google may also use the H1, prominent text, og:title, and anchor text when generating a result title.

Strong task pages repeat the same task across the URL, title, H1, description, and opening without repeating the same sentence:

URL:         /docs/webhooks/verify-signatures/
<title>:     Verify webhook signatures | Orbit Docs
H1:          Verify webhook signatures
Description: Validate Orbit webhook signatures and reject replayed requests.
Opening:     Use the signing secret and timestamp header to verify each payload.

Reading the headings without the sidebar shows whether the procedure still makes sense. “Create an API key” and “Recover from an expired key” survive that test, while “Setup” and “Errors” depend on navigation context that search visitors may never see.

The task is complete only when the page carries a reader through the required access and versions, a working command or request, expected output, recognizable failure symptoms, recovery, and cleanup. The technical tutorial guide shows how to test that path from a clean environment.

Return version-sensitive pages to the review queue when an SDK release, renamed field, changed permission, UI move, deprecation, support pattern, or ranking loss makes the instructions suspect. The updated date should change when the page itself changes meaningfully, not merely because the review took place.

6. Performance, mobile, and structured data

Documentation sites reuse a small number of templates across many URLs, which makes template choice part of the evidence. Sample a task guide, API reference, search-results page, and versioned page because a fast homepage says little about how those heavier layouts behave.

Core Web Vitals

Field data shows whether visitors experienced a problem, while lab tests reproduce it on the affected template. Documentation regressions often come from client-side search, syntax highlighting, large navigation trees, embedded consoles, chat widgets, and layout shifts when code or fonts load.

Those three measurements become useful when they sit beside the element or script responsible. Largest Contentful Paint, Interaction to Next Paint, and Cumulative Layout Shift should lead to a specific template change and another test of the same page, not another generic score on a release checklist.

Mobile documentation pages

Test a narrow viewport and browser zoom because code, tables, and navigation often fail there before the prose does. The page passes when code blocks and tables scroll inside their container, while drawers, copy controls, search, feedback, and chat overlays leave the task visible.

The same pass follows a few heading anchors and looks at long endpoint names near sticky navigation. These details matter even when most developers first discover the page on desktop because the template and indexing signals still serve every device.

HTTPS and structured data

A clean documentation path loads the canonical page and its required resources over HTTPS without mixed content. Route HTTP and alternate-host requests to the preferred URL before those variants spread through internal links or the sitemap.

Structured data should follow the visible page rather than inventing a richer result. When Article or TechArticle and BreadcrumbList fit, compare the URL, headline, dates, author, and breadcrumb path with the canonical page before validating the markup.

7. Run the documentation SEO audit script

I built a small standard-library Python auditor for this guide. It checks one page's response, robots.txt access, index directives, title, description, canonical, H1, language, internal links, anchor text, image alt attributes, and sitemap membership.

The documentation SEO audit script runs as a standalone file:

python3 docs-seo-audit.py \
  https://developers.cloudflare.com/workers/get-started/guide/ \
  --json cloudflare-docs-audit.json

The command makes read-only requests and returns a human-readable report plus a JSON receipt.

Cloudflare Workers audit result

I ran the auditor against Cloudflare's Workers CLI getting-started guide. It returned 12 passes, zero warnings, and zero errors.

The receipt records the URL and evidence for each source-HTML check.

The rendered page also exposes its place in the wider documentation system through the global directory, Workers sidebar, breadcrumbs, page title, outline, prerequisites, and first task.

The page keeps the current task visible inside the wider product documentation.

Audit failure test

I ran the same script against a deliberately broken local fixture. The fixture had noindex, an empty title, no canonical, two H1 elements, no crawlable internal links, and an image without an alt attribute.

The script exits unsuccessfully when it finds blocking index or title problems.

Audit script limitations

The script inspects one page's source HTML. It does not crawl the entire site, execute JavaScript, test Core Web Vitals, confirm Google's selected canonical, or prove that the page deserves to rank.

Use the script as the first gate because it turns obvious source-level failures into an inspectable receipt. The wider audit still needs a rendered-browser review, a link crawl, Search Console URL Inspection, field performance data, and a human attempt to complete the task.

8. Measure documentation search performance

A baseline gives the team a point of comparison before a title, canonical, internal-link path, template, or version policy changes. Save the page and query data with the release date, then compare equivalent windows after search engines have had time to recrawl the page.

Clicks, impressions, CTR, average position, index state, and the URL selected for the query each describe a different part of the result. The process has worked when the team can explain what moved, test the likely cause against the page and competing results, and choose the next change without guessing.

Technical SEO checklist for documentation sites

Use this checklist during the release review.

Search intent

[ ] The page names one reader, task, and successful outcome.
[ ] Site search and web search show no stronger page for the same intent.
[ ] Marketing, support, reference, tutorial, and version pages have distinct jobs.
[ ] One canonical page owns the task.

Discovery and crawling

[ ] At least one relevant indexable page links to the URL.
[ ] Links use <a href> and resolve without a click handler.
[ ] The canonical URL appears in the XML sitemap.
[ ] The final response returns the correct status and HTML content type.
[ ] robots.txt allows required crawling.
[ ] Initial and rendered HTML contain the task content, links, and canonical.
[ ] Error pages return honest status codes instead of soft 200 responses.

Indexing and canonicalization

[ ] No accidental page-level or header-level noindex exists.
[ ] The preferred page has an absolute self-referencing canonical.
[ ] Redirects, internal links, sitemap entries, and structured data use the same URL.
[ ] Parameters, print views, and trailing-slash variants are handled deliberately.
[ ] Language and version pages have a documented indexing policy.
[ ] Search Console confirms the intended canonical after processing.

Page quality

[ ] URL, <title>, H1, description, and opening name the same task.
[ ] The title is unique, concise, current, and free of boilerplate stuffing.
[ ] Headings expose the procedure when read without the sidebar.
[ ] Prerequisites and supported versions appear before dependent steps.
[ ] Commands and examples run in the promised environment.
[ ] Expected output, failure symptoms, recovery, and cleanup are present.
[ ] Images have contextual alt text and useful captions.
[ ] Code, tables, navigation, and overlays work at narrow widths and browser zoom.

Performance and structured data

[ ] Field and lab performance checks cover representative documentation templates.
[ ] Client-side search, syntax highlighting, consoles, fonts, and widgets do not block the task.
[ ] Code blocks and tables do not create page-level horizontal overflow.
[ ] Every canonical page and required resource loads over HTTPS without mixed content.
[ ] Article or TechArticle and BreadcrumbList fields match visible content and the canonical URL.

Measurement

[ ] Page-query performance and index state are saved before and after changes.
[ ] Publish and update dates are annotated beside the measurement window.
[ ] Growth and decline are recorded separately from proposed causes.
[ ] The page has an owner and product-triggered update conditions.
[ ] Review dates match the site's crawl rate and query volume.

Start with one documentation path

Begin with one setup, authentication, deployment, troubleshooting, or migration path that affects product use. Complete and measure that path before expanding the audit to the rest of the documentation site.