What a Documentation Homepage Must Help Users Do

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.

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.