Documentation conventions

What every badge, icon and section on a resource page means — and why the pages are all shaped the same way.

Page shape #

Every resource page presents the same blocks in the same order:

The answer block — type name, one-sentence purpose, and four facts: how many properties are required, what Ref returns, how many Fn::GetAtt attributes exist, and how many properties force replacement.
Minimal template — the smallest thing that deploys, in YAML, JSON and where useful AWS CDK.
Authored prose — overview, remarks, and the operational knowledge that a schema cannot carry.
Properties — the interactive explorer.
Return values — Ref and every Fn::GetAtt attribute, with the value each resolves to.
Required permissions — the IAM actions the handlers call.
Examples — links to worked scenarios, each its own page.
Related types.

The order is fixed on purpose. Once you have read one page you know where everything is on all of them, and you can go straight to the section you came for.

Requiredness #

Badge	Meaning
Required	Must be present. The stack fails validation without it.
Conditional	Required in some circumstances. The property’s detail panel states which.
No badge	Optional.

Required properties sort to the top of the explorer automatically, before conditional ones, then optional, then read-only, then deprecated. This is the main deliberate departure from the AWS reference, which lists properties alphabetically and buries the two you must set among the twenty you need not.

Update behaviour #

The most operationally important signal on the page, and the one the AWS reference renders as small grey text.

Icon	Meaning	What happens
	No interruption	The property changes in place. The resource keeps its physical ID and stays available.
	Some interruption	The resource is briefly unavailable — typically stopped and started — but survives.
	Replacement	CloudFormation creates a new resource and deletes the old one. New physical ID. Anything referencing the old one by ID or ARN breaks.
	Not applicable	The property cannot be updated in isolation.

Mutability and visibility #

Icon	Meaning
	Create-only. Setting a different value replaces the resource.
	Read-only. Returned by the resource; cannot be set in a template.
	Write-only. Accepted on write and never returned — invisible to describe calls and to drift detection.
	Deprecated. Still accepted; the detail panel says what to use instead.

Callouts #

The vocabulary is borrowed from the .NET reference, whose best idea is that remarks — the paragraph explaining what the signature cannot — deserve to be a first-class section rather than a footnote.

The property explorer #

Three views over the same schema, switched from the toolbar.

Tree is the default. Each row is one property; clicking it opens the full reference and its nested properties in the same panel, so nested types never cost a page load. The filter box matches names and descriptions across the whole tree and reveals the path to every hit. Every property has a stable anchor, so #p-BucketEncryption-ServerSideEncryptionConfiguration links straight to it.

Table is every property at two levels of depth in one dense grid, sortable by eye. Use it to answer “what replaces this resource” in one glance.

Template is the generated JSON and YAML skeleton — the AWS “Syntax” section, kept as an option rather than imposed as the opening of the page. It defaults to required properties only, so it is something you can paste rather than something you must edit down.

Coverage #

Where a type is documented in part rather than in full, a Curated subset note appears at the top of its property list, saying what was left out and why, and linking to the authoritative AWS reference.

Everything documented is documented completely: if a property appears in the explorer, its constraints, defaults, allowed values and update behaviour are there too.