Skip to content

docs(style-guide): reshape the Overview and say each fact once - #2658

Merged
marcus-souza-azion merged 2 commits into
mainfrom
docs/overview-definition-budget
Nov 17, 2026
Merged

marcus-souza-azion merged 2 commits into
mainfrom
docs/overview-definition-budget

Conversation

@marcus-souza-azion

@marcus-souza-azion marcus-souza-azion commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

What & why

Related issue: none
Pages affected: /documentation/style-guide/content/overview/, /documentation/style-guide/content/reference/, /documentation/style-guide/content/information-architecture/, /documentation/style-guide/writing/sentence-structure/, /documentation/style-guide/writing/terminology/, /documentation/style-guide/writing/word-choice/, and their pt-br twins

Leadership found the Overview pages too long and their prose prolix. On the Applications Overview, the opening block had grown to ten sentences, and three of them ran past the 25-word cap. It named none of the three Platform Resources nested in Applications, and the page also carried a code specimen, a Resources section, and a block of scope and limits. This PR reshapes the Overview and adds three writing rules for every page.

The Overview (content/overview):

  • The definition block is one paragraph of at most four sentences. A sentence that names every nested Platform Resource joins it.
  • What the Platform Resource offers is a list with no heading, in the opening prose and before the CTAs. Nested Platform Resources come first, then every Feature or entity that has a page of its own. Each item takes two sentences and about 40 words. It says what the reader uses the item for, never what it is or how it works.
  • The specimen (## <Resource> structure), the Resources section, the boundaries block, and capability sections leave the Overview. The page is the definition block, the list, the CTAs, the mechanism, and the router, which links every page of the section.
  • The Template and the Examples follow the new shape, with the Applications block and list as the example.

Scope moves to the Limits page (content/reference, content/information-architecture): a Limits page opens with a ## Scope block before its tables.

Three rules for every page (writing/sentence-structure):

  • A paragraph answers one reader question in at most four sentences, down from six.
  • A new section, Say each fact once, states each fact once in the unit the reader takes in: the whole page on an Overview, one full statement with one-clause recalls on a concept page, and the step, row, or entry elsewhere.
  • The first sentence of a section answers its heading in about twenty words.

Terminology (writing/terminology): an item of the Overview's list carries no class, and the concept example no longer uses the reverse proxy.

Interface paths outside a task (writing/word-choice, second commit): a page that is not a task states a relation or a setting and links the guide that sets it. The exception for the one place where Azion Console sets a relation is removed. A reference page names Azion Console in two forms: a setting described by its Console label next to its API field, or one line saying where the setting is, as an alternative to the API field. A Console string quoted as evidence stays as it is. A sample of concept and reference pages from other documentation sites showed no interface path inside a concept's explanation, and showed interface labels on reference pages in these two forms.

The azion-docs-writer skill change that applies the same rules, with its review checks and style gate, is in a separate pull request in the toolkit repository.

How I checked it:

  • I applied the rules to the Applications Overview and How it works pages in a trial, then rewrote both again with a fresh agent that had only the skill. I compared the two results. Those pages are not in this PR: they move in their own pull requests, section by section.
  • Prettier passes on every changed file. pnpm lint:links reports nothing on the changed pages, and every link this PR adds resolves to a page in its language.
  • Not verified: I did not run pnpm build:local or open the pages in a browser.

Type of change

  • 🆕 New content (feat)
  • 🩹 Fix (fix) — typo, broken link, wrong information
  • ♻️ Content update (docs) — rewrite, expansion, upkeep
  • 🌐 Translation sync (i18n)
  • 🏗️ Platform / structure (refactor / chore) — reviewed by UXE, no content mixed in

Author checklist

  • PR title follows type(scope): summary (see GOVERNANCE.md §4)
  • Frontmatter complete: title, description, meta_tags, namespace, permalink, last_reviewed — every changed page keeps the first five fields, and none has last_reviewed, which the whole corpus lacks; this PR changes no frontmatter
  • No legacy "edge-" product names in the copy — no added line carries one
  • How-to/tutorial content includes at least one runnable, copy-paste-tested code block — no how-to or tutorial page is in this PR
  • Screenshots (if any) have alt text and follow image standards — no screenshot is added or changed
  • Internal links are relative and resolve locally — internal links are root-absolute with the language prefix, and every link this PR adds resolves to a page in its language
  • If any permalink changed or page moved: redirect added in this PR — no permalink changed and no page moved
  • i18n: pt-br updated in this PR or follow-up i18n issue created: — every en change has its pt-br twin in the same commit
  • I ran pnpm build:local (build + frontmatter check) without errors — not run

Overview pages:
- the definition block is one paragraph of at most four sentences, and one
  sentence names every nested Platform Resource;
- what the Platform Resource offers is a heading-less list in the opening
  prose, before the CTAs: nested Platform Resources, then every Feature or
  entity with a page of its own; each item says what the reader uses it for,
  in two sentences, never what it is or how it works;
- the specimen, the Resources section, the boundaries block, and capability
  sections leave the Overview; the scope moves to a Scope section on the
  Limits page, and the router links every page of the section.

Writing rules for every page:
- a paragraph answers one reader question in at most four sentences;
- each fact is said once in the unit the reader takes in;
- the first sentence of a section answers its heading.
A page that is not a task states a relation or a setting and links the
guide that sets it, with no exception for the one place where Azion
Console sets a relation. A reference page names Azion Console in two
forms: a setting described by its Console label next to its API field, or
one line saying where the setting is, as an alternative to the API field.
@marcus-souza-azion
marcus-souza-azion merged commit 539f41b into main Nov 17, 2026
10 checks passed
@marcus-souza-azion
marcus-souza-azion deleted the docs/overview-definition-budget branch November 17, 2026 21:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant