Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Last updated on

New product

↑ Docs content model

A new product doc set is the complete set of documentation for a net-new product or major surface that has no existing docs. It is the largest doc set: a reader arriving with no prior context must be able to understand what the product is, get it working, and then accomplish real tasks.

When to use​

Use this doc set when:

  • The product or surface is entirely new to the documentation, with no existing landing page or section. It is not part of an existing feature.
  • The change introduces its own top-level concept that readers must learn before they can use it.
  • This doc set also applies for a very large new feature within an existing feature group. For example, a new Genie experience and front end within the Genie family of products can be treated as a new product, but is placed within the Genie section of the docs sidebar.

For a smaller addition inside a product that already has docs, use New feature instead.

Composed of​

A new product doc set is assembled from these page types:

  • A section landing page. For larger doc sets, this may just be a list of the pages (or important pages) in the doc set. For smaller doc sets, this might be combined with the concept page.
  • One or more concept pagesthat explains what the product is and how it works.
  • Zero or more tutorial pages that takes a reader from nothing to a working result.
  • One or more procedural pages that describe how to use the product or feature, broken down by task.
  • A product may include the following pages [Links TBD, as this isn't complete yet]:
    • Best practices
    • Limitations
    • FAQ

Typically, on first publishing the docs for a new feature, and when they are promoted from one release type to another, the PR includes:

Technical details​

A new product doc set touches more than the pages themselves:

  • Section and folder. New products usually get their own folder under docs/web/docs/ and a landing page. Decide the folder name and where it sits before writing.
  • Sidebars. Add the new pages to the sidebar for every applicable cloud (sidebars/sidebar_aws.yaml, sidebar_gcp.yaml, sidebar_azure.yaml, and, in rare cases, sidebar_sap.yaml).
  • Terminology. If the product introduces a name that needs to be spelled correctly, or that localizes per cloud, add it to config/global-replacements.yaml and use the replace atom rather than hardcoding the name.
  • Redirects. A net-new product rarely needs redirects, but confirm no placeholder or beta path is being replaced.

Rules​

  • Every new page must appear in the sidebar for each cloud where the product is available.
  • The tutorial must be runnable end to end by a reader who has only completed its prerequisites.
  • Product names that vary by cloud must go through the replace atom, not be hardcoded.

Style​

  • Lead with what the reader can do, not with architecture. The concept page can go deep; the tutorial and how-to pages should stay task-focused.
  • Introduce the product name in full on first use on each page, then use the short form.

Template​

Track a new product doc set as a checklist:

Markdown
- [ ] Concept / landing page — what it is, how it works
- [ ] Tutorial — first working result
- [ ] How-to page(s) — common tasks
- [ ] Reference page — syntax or API (if any)
- [ ] Release note
- [ ] Sidebar entries for every applicable cloud
- [ ] Terminology added to global-replacements.yaml (if the name localizes)

Examples​

A new product that introduces a workspace surface typically ships as: a landing/concept page, a "Get started" tutorial (see Tutorial for the worked example), two or three how-to pages, and a release note — all added to the AWS, Azure, and GCP sidebars.

On this page