Skip to main content
A long page isn’t automatically a bad page. A twenty-step procedure with one clear outcome can be easier to follow than five short pages that make readers jump back and forth. Don’t end pages at arbitrary lengths. Split up procedures when readers reach a meaningful task or stage boundary.

​
Keep one outcome on one page

Keep a procedure together when:
  • Every reader follows roughly the same path
  • The steps lead to one clear outcome
  • Readers are likely to complete the work in one sitting
  • Splitting the page would make them carry details from one page to the next
A page can scroll and still be easy to follow. Clear step titles, useful headings, and visible success criteria matter more than the raw number of steps.

​
Split at a meaningful boundary

A page break should mark real progress. Strong reasons to split a procedure include:
  • Readers complete a distinct milestone before moving on
  • The next stage has different prerequisites or applies to a different audience
  • There’s a natural pause where readers may stop and return later
  • One stage needs enough explanation or troubleshooting to distract from the main procedure
Name each page for what the reader accomplishes:
  • Connect your repository
  • Configure deployments
  • Publish your site
Avoid labels such as “Setup, part 1” and “Setup, part 2.” They describe the document’s structure, not the reader’s progress. If only some readers need the next stage, say who should continue and who is finished. For procedures with substantially different paths, create separate guides and route readers before the paths diverge.

​
Connect the pages

Guide users forward at the end of each page.
Example of a card component used for a next step link
Next steps can be simple, like a single sentence with a link. The end-of-page lesson covers when to use a card and when a sentence is enough. Users who complete a page shouldn’t have to return to an index to find out what comes next. Tell them what they accomplished, what the next page helps them do, and whether continuing is optional.

​
Update the navigation

When a procedure spans multiple pages, make sure the navigation reflects the sequence. In docs.json, list the pages in order within a group:
Example group
The sidebar order communicates the sequence. A user who gets lost can look at the sidebar and see where they are in the overall flow.

​
Don’t hide required stages

Accordions can keep optional explanations and troubleshooting close to a step. They shouldn’t contain an entire required stage of a procedure. Collapsing required work makes it look optional and makes the overall process harder to scan. If the stage is required and substantial, keep it visible or give it a focused page. If it’s optional help, an accordion may be the right fit. Next up: Progressive disclosure with accordions—keep optional details nearby without hiding the main path through a procedure.