add-relevant-docs

Add and Improve Relevant Docs

Use this skill when auditing or adding documentation links and help text to console UI pages and forms.

Overview

The console links to Oxide documentation in two ways:

1. DocsPopover — info button in page headers that opens a popover with a summary and doc links. Used on list/detail pages.
2. ModalLinks / ModalLink — "Relevant docs" section at the bottom of side modal forms. Used in create/edit forms.

Workflow

1. Identify the docs content

Fetch the docs site LLM summary to understand available pages and sections:

Primary: https://docs.oxide.computer/llms.txt

If a specific release version is relevant (e.g., v18), also check the preview site first:

Preview: https://docs-git-v<VERSION>-oxidecomputer.vercel.app/llms.txt

The preview site has the same URL paths — only the hostname differs. Always use docs.oxide.computer for the actual link URLs stored in code, since the preview content will be live there once published.

For detailed section anchors on a specific page, fetch the page directly and inspect headings. For example:

https://docs-git-v<VERSION>-oxidecomputer.vercel.app/guides/configuring-guest-networking

2. Check the OpenAPI schema for context (optional)

The OpenAPI spec at https://github.com/oxidecomputer/omicron/blob/main/openapi/nexus.json contains endpoint descriptions and type documentation that can inform help text. Use this when:

• You need to understand what an API field does
• The docs site doesn't cover a specific concept
• You want to verify terminology

The schema is large — fetch specific sections rather than the whole file. Use the GitHub raw URL with a path to the relevant section, or search for specific endpoint/type names.

3. Add link entries to app/util/links.ts

All documentation URLs live in the links object, and display-ready link configs live in the docLinks object.

Pattern for links (alphabetical order):

export const links = {
  // ...
  routesDocs: 'https://docs.oxide.computer/guides/configuring-guest-networking#vpc-subnet',
  // ...
}

Pattern for docLinks (alphabetical order):

export const docLinks = {
  // ...
  routes: {
    href: links.routesDocs,
    linkText: 'VPC Subnet Routing',
  },
  // ...
}

4. Add DocsPopover to page headers

Used on list pages and detail pages inside <PageHeader>.

File: app/components/DocsPopover.tsx

import { DocsPopover } from '~/components/DocsPopover'
import { docLinks } from '~/util/links'
;<PageHeader>
  <PageTitle icon={<SomeIcon24 />}>Page Title</PageTitle>
  <DocsPopover
    heading="resource name" // lowercase — renders as "Learn about {heading}"
    icon={<SomeIcon16 />} // 16px icon variant
    summary="One-sentence description assuming competent users."
    links={[docLinks.someLink, docLinks.anotherLink]}
  />
</PageHeader>

5. Add SideModalFormDocs to side modal forms

Used at the bottom of SideModalForm and ReadOnlySideModalForm content. The component renders a FormDivider automatically before the links.

File: app/ui/lib/ModalLinks.tsx

import { SideModalFormDocs } from '~/ui/lib/ModalLinks'
import { docLinks } from '~/util/links'

// Inside the form, after form fields:
;<SideModalFormDocs docs={[docLinks.someLink]} />

For custom links not in docLinks, use ModalLinks and ModalLink directly:

import { ModalLink, ModalLinks } from '~/ui/lib/ModalLinks'
import { links } from '~/util/links'
;<ModalLinks heading="Relevant docs">
  <ModalLink to={links.somePageDocs} label="Human-Readable Label" />
</ModalLinks>

6. Write good microcopy

Guidelines:

• Assume competence. Users know what VPCs, subnets, and firewalls are. Don't explain basic concepts.
• Be concise. One sentence for DocsPopover summaries. Short phrases for empty states and tooltips.
• Spell out constraints and consequences, not mechanics. "Gateways can only be modified through the CLI or API" is better than "For now, gateways can only be modified through the API."
• Use consistent voice. Imperative for actions ("Attach an IP pool"), declarative for descriptions ("Routers contain routes that control how traffic is forwarded").

7. Existing examples to reference

8. Verify changes

npm run lint
npm run tsc
npm run fmt