Skip to main content

How to use these docs

The site is organized as documentation sets, one per product. The Overview set is public. Each product set shows its overview to everyone and the rest to organizations that hold the product. Sign in, fill in your organization profile once, and every sample value on every page becomes your own.

The sets​

SetPathAccess
Platform/platform/Public and indexed by search engines
AWS Enterprise Baseline/aws/baseline/Overview public; the rest needs sign-in and the aws-baseline product
Azure Enterprise Baseline/azure/baseline/Overview public; the rest needs sign-in and the azure-baseline product
GCP Enterprise Baseline/gcp/baseline/Overview public; the rest needs sign-in and the gcp-baseline product
Each blueprintlisted at /blueprints/Overview public; the rest needs that blueprint's product

Gated pages are served with no-store and noindex headers, so they are never cached by a shared cache or listed by a search engine. Opening the root of a gated set without the product redirects you to its public overview.

Signing in​

Sign in from the navigation bar. Your account belongs to an organization, and the organization carries the products it holds. BuiltForProd staff set those products when a purchase completes; you cannot grant them to yourself. If your organization holds several products, one sign-in opens all of them. An organization admin can invite colleagues from the same email domain from the Team page.

Placeholders that become your values​

Pages are written with sample values. A build-time step turns each occurrence into a component that renders your organization's value when you are signed in, or the sample when you are not or when no value has been saved.

SampleMeaning
acmeOrganization abbreviation, the namespace that prefixes every resource name
ACMEUpper-case form, the prefix of the SSO groups
your-github-orgGitHub organization
company.comPrimary domain
internal.company.comInternal DNS zone
us-west-2, usw2AWS home region and its slug
111111111111Management account id; each of the fifteen accounts has its own repeating sample id
eastus2, eus2Azure home region and its slug
aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaMicrosoft Entra tenant id
11111111-1111-1111-1111-111111111111Root subscription id; each of the fifteen subscriptions has its own repeating sample id
us-west1, usw1GCP home region and its slug
161616161616GCP organization id
AAAAAA-BBBBBB-CCCCCCGCP billing account id
C0aaaaaaaCloud Identity customer id

Substitution works inside identifiers too: the AWS development cluster acme-usw2-dev-eks, the Azure state storage account stacmeeus2roottfstate and the GCP state bucket acme-usw1-root-tfstate render with your namespace and region slug. GCP project ids need no sample of their own: they are built from the namespace, so acme-plat-dev renders with yours. Organization admins enter the values on the Organization profile page; each value is validated before it is saved (an account id must be twelve digits, an AWS region must be one of the AWS regions offered, an Azure or GCP region must have the form of a region name such as eastus2 or us-west1, a subscription id must be a GUID, a billing account id must be three groups of six characters). The profile asks only for the values of the clouds your organization holds. The privacy page says where those values are stored and who can read them.

A sample resource name and what a signed-in reader sees
acme-usw2-prd-vpc the sample, shown to anyone
contoso-euw1-prd-vpc the same line for an organization whose namespace is contoso in eu-west-1

Search is split by set. On a Baseline page, that edition's set is searched first; on an Overview page, the Overview set. The index holds the sample values, so search for acme-usw2-dev-eks rather than your own cluster name.

Every page ends with two blocks generated from its front matter: What's next, the one to three pages to read after this one, and Related topics, the two to six pages that cover the same ground from another angle. Following What's next from a set's first page reads the set in order. The key concepts page is the usual first stop.

Conventions on every page​

  • The first paragraph answers the page's question.
  • Diagrams are Mermaid, drawn from the code, and use the site theme's colors.
  • Configuration is shown as it is in the repositories, with a caption naming the file.
  • Acronyms are expanded on first use; the glossary holds the definitions and links to the explainer for each service and tool of each edition.
  • Customer pages describe the platform and how to operate it. Deployment procedures, bootstrap steps and credentials are not published here.

The account pages​

PageWhat it doesWho
Sign inOpens the sign-in formEveryone
TeamLists members and pending invitations; invite by email, change a role, remove a memberOrganization admins
Organization profileThe placeholder values for your organizationOrganization admins edit; members read

The reading paths by role page tells each kind of reader which pages to open, in which order.