Repository navigation
docs(style-guide): reshape the Overview and say each fact once - #2658
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 theirpt-brtwinsLeadership 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):## <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.Scope moves to the Limits page (
content/reference,content/information-architecture): a Limits page opens with a## Scopeblock before its tables.Three rules for every page (
writing/sentence-structure):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-writerskill 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:
pnpm lint:linksreports nothing on the changed pages, and every link this PR adds resolves to a page in its language.pnpm build:localor open the pages in a browser.Type of change
feat)fix) — typo, broken link, wrong informationdocs) — rewrite, expansion, upkeepi18n)refactor/chore) — reviewed by UXE, no content mixed inAuthor checklist
type(scope): summary(see GOVERNANCE.md §4)title,description,meta_tags,namespace,permalink,last_reviewed— every changed page keeps the first five fields, and none haslast_reviewed, which the whole corpus lacks; this PR changes no frontmatterpt-brupdated in this PR or follow-upi18nissue created: — everyenchange has itspt-brtwin in the same commitpnpm build:local(build + frontmatter check) without errors — not run