Navigation hubs

Purpose

A navigation hub sends the reader deeper into the documentation. It carries links and one sentence of orientation, and nothing else.

It applies no Diátaxis base form. A hub does not teach, instruct, describe, or explain: it routes. That is why it has no sentence budget for prose it should not be carrying.

When to use

• Write a hub when a section holds more pages than a sidebar makes legible.
• Write one for a section that gathers pages from several products, such as a Solution area of the guides hub, or the architectures index.
• Write one for the Guides and tutorials slot of a product section, which is a single sidebar row pointing at a hub rather than a dropdown. Information architecture holds that rule.

Do not write a hub when:

• The section is a product. A product opens with an Overview, which orients and links.
• The page would explain what the section is about at length. That is a concept page.
• The sidebar already makes the pages findable. A hub that duplicates the sidebar is a second thing to maintain and a second thing to go stale.

Register

Descriptive: 25 words per sentence, active voice, passive only when the actor is unknown. Tone: brief, plain, orienting. Sentence structure holds the rules.

Structure

Both shapes open the same way and close the same way. Only the body differs.

• Opening move: one orientation sentence saying what the section holds.
• Closing: none. The last link or the last table row ends the page.

Shape 1: grouped links

The default. Use it when the destinations differ from each other and the reader needs a sentence to tell them apart.

• Body: link groups under noun-phrase ## headings.
• Link shape: [Title](/path/) - one sentence on what the reader gets there.

Shape 2: a table

Use it when the hub lists one homogeneous set and the reader chooses by effort and freshness rather than by description. The Guides and tutorials slot is this shape, because every row is a how-to or a tutorial for the same product and a per-row sentence would repeat the page title.

• Body: one <ProductGuidesSection>, no ## headings and no groups.
• Columns: name, type, last updated.
• The table is generated, never typed. A page appears when the guides catalog tags it with the product, its type comes from the catalog, and its date from the page’s last change, so the hub cannot fall out of step with the pages it lists. A resource’s hub also lists the guides of the Products nested in it; a nested Product has no hub of its own.

Template

Copy the template for the shape you need and replace each <placeholder>.

Grouped links:

A table:

Rules

• No closing section and no other prose. One sentence of orientation; explanation belongs in a concept page.
• Make every link earn its place. A hub is judged by what it leaves out; one that lists everything ranks nothing.
• Write descriptions that differentiate. Say what this page gives that its neighbours do not.
• Group when the list passes seven, by what the reader is trying to do. A table does not group: it sorts, newest first. The Platform resources group of the root sidebar is the one exception: every Platform resource in the order the reader adopts them, by decision, because grouping them by intent would restore the retired pillars.
• Pick the shape by what the reader compares. Mixed destinations need a sentence each, so they take grouped links. One kind of page, compared on effort and freshness, takes the table.
• Never hand-write a table row. A typed date is wrong the first time somebody forgets it, which is why this is the one place the guide allows a date outside a changelog.
• Register the page in the guides catalog. A page the catalog does not list is missing from the hub. The first product the catalog names for a page owns it and names its topic in the Guides section.
• Keep it in step with the section. Update the hub in the same change that adds a page.
• Set type: homepage only on a card-grid hub. Every other page omits the field. For more information, refer to Frontmatter.

Examples

• Use Cases - One line of orientation, then the designs grouped by Solution.
• Applications guides and tutorials - The table shape: one sentence, then every guide and tutorial with its type and date.

An Object Storage hub, trimmed to its orientation sentence and first group:

Related