diff --git a/apps/docs/src/content/docs/en/pages/style-guide/components.mdx b/apps/docs/src/content/docs/en/pages/style-guide/components.mdx index e2dd9a7e3c..12b845371a 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/components.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/components.mdx @@ -106,12 +106,12 @@ import Code from '~/components/webkit/CodeBlock.vue' ``` - `client:visible` is mandatory. Without it the tabs render and do not switch. -- A block pairs each `tab.x` with a `panel.x`. The one exception is a page that documents more than one interface, such as a [Quickstart page](/en/documentation/style-guide/content/quickstart/) or a [how-to guide](/en/documentation/style-guide/content/how-to-guides/): the prerequisites block declares the tab strip, and every later block of the same `sharedStore` holds only `panel.x` slots. A panel-only block of the `interface` store renders that strip above its own panels, so the reader switches at any section. +- A block pairs each `tab.x` with a `panel.x`. The one exception is a page that documents more than one interface, such as a [Quickstart page](/en/documentation/style-guide/content/quickstart/) or a [how-to guide](/en/documentation/style-guide/content/how-to-guides/). On that page, the prerequisites block declares the tab strip, and every later block of the same `sharedStore` holds only `panel.x` slots. A panel-only block of the `interface` store renders that strip above its own panels, so the reader switches at any section. - **Blank lines around markdown inside a Fragment are mandatory**, or the markdown renders as one literal paragraph. - Panels are paired to tabs by key, and the first tab is the default. An `interface` block renders its tabs in one order on every page, whatever order the MDX declares them in: Console, GraphiQL, CLI, GitHub, API. Write them in that order anyway, so the page and its Markdown twin read the same. - Canonical keys: `tab.console`, `tab.api`, `tab.cli`, plus `tab.apiv3` / `tab.apiv4` for versioned APIs. A key is lowercase letters and digits only: a hyphen escapes the `tab.x` / `panel.x` pairing check without failing it. - In a block with `sharedStore="interface"`, open every panel with a heading one level below the section it sits in, carrying the tab label: `### Console`. These headings stay out of the table of contents, and each one links to its section with its interface selected: `?interface=console#create-a-database`. -- Optional `sharedStore=""` syncs selection across tab groups on a page. Interface tabs use `sharedStore="interface"`, so one selection follows the reader down a page that repeats the tabs per section, and on to the next page: that one store is kept in the browser and written to the URL as `?interface=`, which leaves the fragment free for a section. Give every block sharing a key the same tabs. A block that does not offer the selected key shows its own first panel instead, and leaves the selection untouched for the blocks that do offer it. +- Optional `sharedStore=""` syncs selection across tab groups on a page. Interface tabs use `sharedStore="interface"`, so one selection follows the reader down a page that repeats the tabs per section, and on to the next page. That one store is kept in the browser and written to the URL as `?interface=`, which leaves the fragment free for a section. Give every block sharing a key the same tabs. A block that does not offer the selected key shows its own first panel instead, and leaves the selection untouched for the blocks that do offer it. ## Tag @@ -163,7 +163,7 @@ Every diagram follows the same rules: - **Open with the shared `init` line** the example shows. It lays the diagram out with ELK, gives the labels room, and shrinks a diagram wider than the column to fit it. When the first node does not render at the top, add an `elk` object right after `"layout": "elk",`. In a diagram with a cycle, such as a request and its response, use ELK's model-order options, so the declaration order decides the layers: `"cycleBreakingStrategy": "MODEL_ORDER"`, or `"preset": "modelOrder", "keepEntryNodeOnTop": true`. In a diagram with more than one starting node, use `"layeringStrategy": "LONGEST_PATH_SOURCE"`, which puts every starting node in the top row. - **Run every flowchart top to bottom** (`flowchart TD`), a chain of steps included. A chain drawn left to right grows wider than the column and shrinks its labels to fit. -- **Give each role one shape.** The client is a stadium (`(["Client"])`), anything on Azion, a Product or a Platform Resource, is a rectangle (`["application"]`), a data store is a cylinder (`[("KV Store")]`), and a system outside Azion is a subroutine (`[["origin server"]]`). A step, a state, or a decision keeps its rectangle or its diamond. +- **Give each role one shape.** The client is a stadium (`(["Client"])`). Anything on Azion, a Product or a Platform Resource, is a rectangle (`["application"]`). A data store is a cylinder (`[("KV Store")]`), and a system outside Azion is a subroutine (`[["origin server"]]`). A step, a state, or a decision keeps its rectangle or its diamond. - **Let the line style say which way the flow runs.** When a diagram draws a request and its response, solid arrows (`-->`) carry the request and dotted arrows (`-.->`) carry the response. A flow that runs apart from any request, such as a purge or a log stream, takes thick arrows (`==>`). ## Steps @@ -252,12 +252,12 @@ import DocItem from '@aziontech/webkit/doc-item' ## Changelog entry -One dated entry: label and version on the left, the notes on the right, with an anchor built from the label. +One dated entry: label and version on the left, the notes on the right, and an anchor on the label. ```mdx import DocUpdate from '@aziontech/webkit/doc-update' - + **Bot Manager** now ships nine new static rules and two new arguments. @@ -265,7 +265,7 @@ import DocUpdate from '@aziontech/webkit/doc-update' ``` - No client directive. Blank lines around the markdown inside are mandatory. -- `label` is the anchor, slugified. Two entries with the same label need distinct `anchor` values. +- Always pass `anchor`. The right rail lists only the entries that carry one, and without it the id falls back to the slugified `label`. Two entries with the same label need distinct `anchor` values. - `description` is the line under the label; `tags` is an array of short labels. - A page of entries outlines them: the right rail lists one row per date and links the first entry with that date, in place of the headings inside the notes. The [Changelog](/en/documentation/style-guide/content/changelog/) pattern holds the rest. @@ -325,7 +325,7 @@ A page about a resource that exists in API v3 and API v4 carries exactly one ver | `versionDualSteps` | The end of the introduction of a guide with steps for API v4 and API v3 | None | API v4 reaches every account. The API v3 steps go with it | | `versionDeprecated` | The top of an API v3 page | A link to the API v4 page, titled as that page | API v4 reaches every account. The page then redirects to its API v4 counterpart, never to a home page | -An API v3 page is not listed in the navigation. Its row in the navigation tree carries `"hidden": true`, so the page keeps the sidebar and breadcrumb of its Platform Resource, and readers reach it from the notice on its API v4 counterpart. +An API v3 page is not listed in the navigation. Its row in the navigation tree carries `"hidden": true`, so the page keeps the sidebar and breadcrumb of its Platform Resource. Readers reach it from the notice on its API v4 counterpart. The date when API v3 shuts down appears only in `versionDeprecated` and on [API v4 Migration](/en/documentation/fundamentals/api-v4-migration/). @@ -345,6 +345,7 @@ import ProductGuidesSection from '~/components/ProductGuidesSection.astro' - `product` — the section's id, such as `applications`. The table lists every guide the guides catalog tags with the section or with a Platform Resource nested in it. - The date is the page's last change, filled in for you. Never write it by hand. +- The table also lists the videos that the navigation's video list tags with the section. A video row opens YouTube in a new tab, its type adds Video, and its date stays empty. - The type column shows each page's content type, in the reader's language. - Rows sort alphabetically by each page's navigation label, in the reader's language, never by date. The name column shows that label, not the page title. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/architecture.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/architecture.mdx index 6a58f00b02..32f3857efb 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/architecture.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/architecture.mdx @@ -28,7 +28,7 @@ Write an architecture page when: Do not write an architecture page when: - The subject is one Platform Resource or one idea. Write a [concept page](/en/documentation/style-guide/content/concept/). -- The reader wants to build the thing. Write the [use-case page](/en/documentation/style-guide/content/use-cases/) that builds it, or a [multi-resource guide](/en/documentation/style-guide/content/multi-resource-guides/), and link it from here. +- The reader wants to build the thing. Write the [use-case page](/en/documentation/style-guide/content/use-cases/) that explains it and links the guides that build it, or a [multi-resource guide](/en/documentation/style-guide/content/multi-resource-guides/), and link it from here. - The catalog has no entry for the design. Propose it to the Use Case catalog first; the page comes after the entry. - The design cannot be drawn. A design you cannot draw is one you do not yet understand well enough to publish. @@ -153,7 +153,7 @@ Content moves through the design in this order: The publish flow moves only on a push, and the two flows meet only at the bucket. ```` -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/changelog.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/changelog.mdx index 012b95d447..44bda7d870 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/changelog.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/changelog.mdx @@ -13,7 +13,7 @@ import DocItem from '@aziontech/webkit/doc-item' ## Purpose -A changelog records notable changes to the platform, newest first. It is a **record**, not one of the four Diátaxis forms: it does not teach, instruct, or explain, and a reader consults it to answer one question, which is what changed and when. +A changelog records notable changes to the platform, newest first. It is a **record**, not one of the four Diátaxis forms: it does not teach, instruct, or explain. A reader consults it to answer one question, which is what changed and when. ## When to use @@ -36,7 +36,8 @@ Each entry is one `DocUpdate`: the date, the version, and the Platform Resource **Required components** -- **A `DocUpdate` entry**, newest first. `label` is the date, ` , `: dates are allowed in changelogs and only in changelogs. `anchor` is the date as a slug, `july-10-2026`. +- **A `DocUpdate` entry**, newest first. `label` is the date, ` , `: a changelog is one of the few places [Numbers and units](/en/documentation/style-guide/formatting/numbers/#format-a-date-only-where-a-date-belongs) allows a date. `anchor` is the date as a slug, `july-10-2026`. +- **One tag**: `tags={['']}`, exactly one. The tag is the current name of the Platform Resource or channel the entry reports on. It comes from the closed list in the [contributing guide](https://github.com/aziontech/docs/blob/main/.github/CONTRIBUTING.md#changelog-entries). - **The opening sentence**: `**** now s .`, plus the concrete detail: the flag, the field, or the default. When the change belongs to a Platform Resource nested in another, the nested one is the subject. - **What it means concretely**: what works without configuration now, or what behaves differently. - **Who is not affected**: existing configurations, earlier versions, accounts that did not opt in. @@ -44,7 +45,7 @@ Each entry is one `DocUpdate`: the date, the version, and the Platform Resource **Optional components** -- **The Platform Resource and the version**: `tags={['']}` and `description="Version "`, when the release names a Platform Resource or a version. +- **The version**: `description="Version "`, when the release has a version. - **Kind headings**: `### Features`, `### Improvements`, `### Bug Fixes` inside the notes, when one entry lists more than one kind of change. - **Migration or opt-in steps**: with a code sample, when an API, CLI, or configuration changed. @@ -53,7 +54,7 @@ Each entry is one `DocUpdate`: the date, the version, and the Platform Resource ```mdx import DocUpdate from '@aziontech/webkit/doc-update' -']} anchor="--"> +']} anchor="--"> **** now s , . @@ -74,7 +75,8 @@ For more information, refer to [](/en/documentation/.../). - **State who is not affected.** A reader's first question about any change is whether it breaks them; answer it before they ask. - **Show migration or opt-in steps when the surface changed.** An API, CLI, or configuration change gets a code sample; two lines is enough. - **Close every entry with the documentation link.** An entry that documents the feature in full is a page filed in the wrong place. -- **Give every entry an `anchor`.** The page outline lists one row per date and links the first entry with that date, so `#` keeps resolving. A second entry on the same date takes `-`: `july-10-2026-marketplace`. +- **Give every entry an `anchor`.** The page outline lists one row per date and links the first entry with that date, so `#` keeps resolving. A second entry on the same date takes `-`, with the tag as a slug: `july-10-2026-marketplace`. +- **Add a tag to the closed list before you use it.** A release that needs a new tag adds it to the list in the contributing guide. The same pull request adds it to the changelog check. `pnpm lint:changelog` reports a new entry that does not carry exactly one tag from the list. - **Leave a blank line after the opening tag and before the closing one.** Without them the notes render as one literal paragraph. - **Never rewrite an entry.** Correct it with a new dated entry; the log is append-only. - **Keep the names of the period.** A dated record keeps the names it was written with; only new entries use current names. @@ -82,7 +84,7 @@ For more information, refer to [](/en/documentation/.../). ## Examples -- [Changelog archive](/en/documentation/changelog/previous-year/): one entry per month, from 2016 to 2021. +- [Changelog archive](/en/documentation/changelog/previous-year/): the entries from before the current release notes, one per month. This trimmed entry shows the date, the tag, and the entry shape: @@ -100,7 +102,7 @@ For more information, refer to [Azion Bot Manager Lite](/en/documentation/platfo ``` -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx index 7d2a548bd4..2419ce8a0f 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx @@ -17,7 +17,7 @@ Every documentation page is written in one of four base forms, from Diátaxis. T | Learn a Platform Resource by doing something that works | [Tutorial](/en/documentation/style-guide/content/tutorials/) | | Accomplish a specific task they already have in mind | [How-to guide](/en/documentation/style-guide/content/how-to-guides/) | | Look up a fact: a limit, a field, a flag, a response code | [Reference](/en/documentation/style-guide/content/reference/) | -| Understand why something works the way it does | Explanation, as a [concept](/en/documentation/style-guide/content/concept/) or [architecture](/en/documentation/style-guide/content/architecture/) page | +| Understand why something works the way it does | Explanation, as a [concept](/en/documentation/style-guide/content/concept/), [architecture](/en/documentation/style-guide/content/architecture/), or [use case](/en/documentation/style-guide/content/use-cases/) page | The forms answer "how do I write this page". The page-kinds catalog answers "which page do I build". @@ -32,7 +32,7 @@ A page kind is a base form plus a place in the [information architecture](/en/do | [Tutorial](/en/documentation/style-guide/content/tutorials/) | Tutorial | No | Teach the Platform Resource by building a goal the author chose | | [How-to guide](/en/documentation/style-guide/content/how-to-guides/) | How-to | No | Complete one task the reader arrived with | | [Multi-resource guide](/en/documentation/style-guide/content/multi-resource-guides/) | How-to | No | Reach a goal that crosses Platform Resources, on one recommended path | -| [Use case](/en/documentation/style-guide/content/use-cases/) | How-to | No | Explain a Use Case from the catalog as a design, with the guides that build it | +| [Use case](/en/documentation/style-guide/content/use-cases/) | Explanation | No | Explain a Use Case from the catalog as a design, with the guides that build it | | [Troubleshooting](/en/documentation/style-guide/content/troubleshooting/) | How-to | No | From a symptom the reader sees to a fix | | [Reference](/en/documentation/style-guide/content/reference/) | Reference | No | Look up fields, values, defaults, and limits | | [Concept](/en/documentation/style-guide/content/concept/) | Explanation | No | Understand how something works and why it is built that way | @@ -41,7 +41,7 @@ A page kind is a base form plus a place in the [information architecture](/en/do | [Glossary](/en/documentation/style-guide/content/glossary/) | Reference | Yes | Define the terms the section's documentation uses, in an alphabetical table | | [Navigation hub](/en/documentation/style-guide/content/navigation-hubs/) | None | No | Direct readers deeper. Links plus one sentence of orientation | -Required per section means required in every Platform Resource section. A Platform Resource nested as a dropdown in another needs only its reference pages, plus a mechanism page when it has a mechanism to explain and a Quickstart when it has a setup of its own; every other page it would have is a section of the resource's pages. The nesting rule is in [Information architecture](/en/documentation/style-guide/content/information-architecture/#nested-platform-resources). +Required per section means required in every Platform Resource section. A Platform Resource nested as a dropdown in another always needs its reference pages. It also needs a mechanism page when it has a mechanism to explain, and a Quickstart when it has a setup of its own. Every other page it would have is a section of the resource's pages. The nesting rule is in [Information architecture](/en/documentation/style-guide/content/information-architecture/#nested-platform-resources). ## Slots are not kinds @@ -55,7 +55,7 @@ Some kinds common in other documentation sets are deliberately absent, because e - **FAQ**: a list of questions is a list of pages in disguise. Route each answer to its kind, and the question becomes a heading a search can find. - **Configuration**: examples of settings and values are reference content. The kind adds a second name for the same page. -- **Design, implementation, and solution guides**: three names for content the catalog already holds. A goal that crosses Platform Resources is a [multi-resource guide](/en/documentation/style-guide/content/multi-resource-guides/). A Use Case from the catalog, built end to end, is a [use case](/en/documentation/style-guide/content/use-cases/). The reasoning behind a design is a [concept](/en/documentation/style-guide/content/concept/) or an [architecture](/en/documentation/style-guide/content/architecture/) page. +- **Design, implementation, and solution guides**: three names for content the catalog already holds. A goal that crosses Platform Resources is a [multi-resource guide](/en/documentation/style-guide/content/multi-resource-guides/). A Use Case from the catalog, explained as a design, is a [use case](/en/documentation/style-guide/content/use-cases/). The reasoning behind any other design is a [concept](/en/documentation/style-guide/content/concept/) or an [architecture](/en/documentation/style-guide/content/architecture/) page. - **Third-party integration guide**: a how-to guide that crosses a vendor's interface. The [third-party rules](/en/documentation/style-guide/content/how-to-guides/) cover it. - **Solution page**: a Solution lives on the website, not in the documentation. Here a Solution is the label of a Guides area and of an Architectures group. The pages are the use cases and architectures under it. - **API guidelines** are not covered by this guide yet. @@ -76,15 +76,15 @@ Reference and explanation both describe; neither form instructs. They differ in Reference is the map. It is complete, consistent, and deliberately plain. Nobody reads a reference from top to bottom. If a reader who scans for a limit value skips a sentence, that sentence does not belong on the page. -Explanation is the discussion. It provides context, alternatives, and reasons. It is the only form where "why" and "instead of" belong. A design decision, a comparison between approaches, or the background of a feature lives in a [concept](/en/documentation/style-guide/content/concept/) or [architecture](/en/documentation/style-guide/content/architecture/) page and nowhere else. +Explanation is the discussion. It provides context, alternatives, and reasons. It is the only form where "why" and "instead of" belong. A design decision, a comparison between approaches, or the background of a feature lives in a [concept](/en/documentation/style-guide/content/concept/), [architecture](/en/documentation/style-guide/content/architecture/), or [use case](/en/documentation/style-guide/content/use-cases/) page and nowhere else. ## Separate multi-resource guides from use cases -Both take the how-to base form and both cross Platform Resources, so the split is worth stating. +Both cross Platform Resources, so the split is worth stating. A multi-resource guide takes the how-to base form, and a use case takes the explanation base form. A multi-resource guide starts from a technical goal. The reader knows what they want to build and needs the route across Platform Resources. It ends when the task is done. -A use case starts from a catalog entry: a customer situation the Use Case catalog already names and places under its Solution. The reader arrives with a situation, not a task. The page names the Platform Resources the scenario needs, shows the architecture, configures it, and proves it works. It is written as a specification an agent can execute. That is why it carries a requirements table and a measurable outcome, which the multi-resource guide does not. +A use case starts from a catalog entry: a customer situation the Use Case catalog already names and places under its Solution. The reader arrives with a situation, not a task. The page explains a design for it: a requirements table of the Products the scenario needs, the architecture, and why the design takes its shape. It also names the metrics that show the outcome. A multi-resource guide carries neither the requirements table nor the metrics. Every step, value, and check lives in the guides the page links, and an implementer, often an agent, builds the design from them. The test runs in two steps. First match the goal to the Use Case catalog: an entry makes the page a use case, whatever the wording of the goal. With no entry, a goal the reader states without a customer situation is a multi-resource guide. A customer situation the catalog should carry is a proposal for a new entry, not a page. @@ -103,11 +103,11 @@ One form per page works because links connect the pages. Each form links out in | Tutorial | The how-to guides of its Platform Resource | In a final "Next steps" section | | How-to guide | Reference | For every setting the steps touch | | Reference | The how-to guide that changes a setting | Sparingly: one link per setting at most | -| Concept or architecture | The reference and the guides that implement the design | Where the design meets practice | +| Concept, architecture, or use case | The reference and the guides that implement the design | Where the design meets practice | Two rules keep the links checkable: -- **Every page closes with links.** A page ends with the closing its kind requires, `## Next steps` or `## Related resources`, holding at least one link to a documentation page. Glossary, changelog, and navigation hub pages are the exceptions, because each is a list of links already. +- **Every page closes with links.** A page ends with the closing its kind requires, and that closing holds at least one link to a documentation page. The closing is `## Next steps` or `## Related resources`, and a use case closes with `## Guides in this use case`. Glossary, changelog, and navigation hub pages are the exceptions, because each is a list of links already. - **No dead ends.** At least one closing link leads deeper into the page's own Platform Resource: a page of that section other than its overview. A closing whose links all point back to where the reader came from is a dead end wearing a closing section. Reciprocity is required only on the section spine: the overview links every page of its section, and every page of the section links the overview. Between any other two pages a link runs one way. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/concept.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/concept.mdx index 17ea61dd82..1a4c8d2f3e 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/concept.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/concept.mdx @@ -117,7 +117,7 @@ Its behavior depends on five mechanisms: the cache layers, the second-layer regi End users send requests to Azion's distributed infrastructure, where content is cached. Without Tiered Cache, a request that misses the first cache layer goes to the origin. Tiered Cache adds a second cache layer between that first layer and the origin servers. The tiered layer can answer a request that misses the first layer, so the request does not reach the origin. Content stays cached for longer periods, and the origin receives fewer requests. ``` -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/glossary.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/glossary.mdx index ac26af0b30..e2b89fc759 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/glossary.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/glossary.mdx @@ -58,7 +58,7 @@ Definitions for the terms the **** documentation uses. The first Platform Resource glossary is the [Functions glossary](/en/documentation/platform/functions/glossary/): 22 terms, each definition linking its canonical page. -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/how-to-guides.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/how-to-guides.mdx index 2deafd64b7..269bf9000a 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/how-to-guides.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/how-to-guides.mdx @@ -39,7 +39,7 @@ Procedural: 20 words per sentence, one instruction per step, imperative and acti **Optional components** -- **Tabs by interface**: when a task runs through more than one interface, the page declares its tab strip once, the first thing under `## Prerequisites`, and each task carries a block of the same store with panels only, which renders that strip above its panels. Console first, one complete procedure per panel, and every panel opens with the interface's name as a heading one level below its section. +- **Tabs by interface**: when a task runs through more than one interface, the page declares its tab strip once, as the first thing under `## Prerequisites`. Each task carries a block of the same store with panels only, which renders that strip above its panels. Console first, one complete procedure per panel, and every panel opens with the interface's name as a heading one level below its section. - **One aside** holding the alternative path, when the task genuinely branches. ## Template @@ -166,7 +166,7 @@ The bucket appears in the bucket list. - [Create request and response rules](/en/documentation/guides/application-development/getting-started/rules-engine/): two tasks on one page, each a named procedure with numbered imperative steps. -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/information-architecture.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/information-architecture.mdx index 8dbb8cef17..151e40853a 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/information-architecture.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/information-architecture.mdx @@ -16,7 +16,7 @@ Two principles organize everything. Sections follow the order of the reader's jo Every Platform Resource section follows this order. The table shows what each slot holds and when it exists. -A Platform Resource type with a section of its own (Workloads, Edge DNS, Applications, Connectors, Firewall) follows the same skeleton. Its Overview describes the resource type, its Quickstart creates the first instance, and Glossary, Pricing, and Changelog are required, as in every section. A Platform Resource nested in another keeps no section of its own: it enters the parent resource's section as a dropdown row in the slot-4 position, and its URL nests under the parent, as in `/documentation/platform/firewall/waf/`. The nesting rule and what the dropdown holds are in [Nested Platform Resources](#nested-platform-resources). +A Platform Resource type with a section of its own (Workloads, Edge DNS, Applications, Connectors, Firewall) follows the same skeleton. Its Overview describes the resource type, its Quickstart creates the first instance, and Glossary, Pricing, and Changelog are required, as in every section. A Platform Resource nested in another keeps no section of its own. It enters the parent resource's section as a dropdown row in the slot-4 position, and its URL nests under the parent, as in `/documentation/platform/firewall/waf/`. The nesting rule and what the dropdown holds are in [Nested Platform Resources](#nested-platform-resources). | Order | Slot | Required | Holds | | --- | --- | --- | --- | @@ -38,7 +38,7 @@ Two slots have a fixed sidebar shape. **Guides and tutorials is one row that opens a page.** The row points at a hub whose body is a single table: name, type, and last updated, one row per guide and per tutorial. The sidebar never expands it, and the reader opens a guide from the table. A section with forty guides stays one sidebar row, so the sidebar keeps showing the whole section. -The table is generated, not written. The date is the page's last change and the type is the content type the guides catalog records for the page, so the hub cannot drift from the pages it lists. +The table is generated, not written. The date is the page's last change, and the type is the content type the guides catalog records for the page. The hub therefore cannot drift from the pages it lists. **Reference is a fixed group.** The sidebar shows a **Reference** parent holding one row per reference page. The group name is the same in every Platform Resource section, so the reader finds the fields in the same place everywhere. @@ -52,11 +52,23 @@ A feature with its own surface repeats the pattern one level down: Tiered Cache ## Nested Platform Resources -A Platform Resource nested in another is a dropdown row inside the parent resource's section, in the slot-4 position, with no group label: WAF, Network Shield, and Bot Manager inside Firewall; Cache, Application Accelerator, and Image Processor inside Applications; Load Balancer, Origin Shield, and Live Ingest inside Connectors; Certificate Manager, Custom Pages, and DDoS Protection inside Workloads. On a page, its class is Platform Resource, whatever the naming catalog lists it as. It keeps only the pages that are its own: its reference pages, a Quickstart when it has a setup of its own, and, optionally, an Overview that the parent's Overview links. Without an Overview, its dropdown gets a group hub, so its crumb in the breadcrumb still opens a page. When it has a mechanism to explain, its Reference group opens with a mechanism page: a [concept page](/en/documentation/style-guide/content/concept/) titled for the mechanism, such as Scoring and modes for WAF. Everything else the reader needs about it is written once, in the parent's pages: what it does and when to turn it on in the parent's Overview, a `## ` section in the parent's How it works that introduces it and links its mechanism page, its limits, practices, and symptoms in the parent's Limits, Best practices, and Troubleshooting, its terms in the parent's Glossary, and its guides in the parent's hub. +A Platform Resource nested in another is a dropdown row inside the parent resource's section, in the slot-4 position, with no group label. Four parent resources hold nested Platform Resources: -A Platform Resource nests when its configuration lives in the parent resource's own settings or rules: a flag in `modules`, a Rules Engine behavior, or a field of the parent. A Platform Resource the reader consumes from code (Functions, Object Storage, SQL Database, KV Store, AI Inference) and a standalone service (Edge DNS, Data Stream, Orchestrator) stay at the root of Platform Resources. A feature is a page inside its Platform Resource, never a dropdown. +- Firewall: WAF, Network Shield, and Bot Manager. +- Applications: Cache, Application Accelerator, and Image Processor. +- Connectors: Load Balancer, Origin Shield, and Live Ingest. +- Workloads: Certificate Manager, Custom Pages, and DDoS Protection. -Quickstart carries the interface inside the page. A Platform Resource whose first run goes through Azion Console, the Azion CLI, or the API keeps one page and selects the interface with tabs, so the slot holds one row and one URL. The slot splits only when the interfaces cannot share one stage skeleton, and for an AI agent, whose path is driven by prompt and shares no stage with the others. Those pages group under Quickstart, with Console first; the group is a sidebar parent with a group hub, not an Overview. [Quickstart pages](/en/documentation/style-guide/content/quickstart/) holds the test. +On a page, the class of a nested Platform Resource is Platform Resource, whatever the naming catalog lists it as. It keeps only the pages that are its own. Those are its reference pages, a Quickstart when it has a setup of its own, and an optional Overview that the parent's Overview links. Without an Overview, its dropdown gets a group hub, so its crumb in the breadcrumb still opens a page. When it has a mechanism to explain, its Reference group opens with a mechanism page: a [concept page](/en/documentation/style-guide/content/concept/) titled for the mechanism, such as Scoring and modes for WAF. Everything else the reader needs about it is written once, in the parent's pages: + +- The parent's Overview says what it does and when to turn it on. +- The parent's How it works holds a `## ` section that introduces it and links its mechanism page. +- The parent's Limits, Best practices, and Troubleshooting hold its limits, practices, and symptoms. +- The parent's Glossary holds its terms, and the parent's hub lists its guides. + +A Platform Resource nests when its configuration lives in the parent resource's own settings or rules: a flag in `modules`, a Rules Engine behavior, or a field of the parent. A Platform Resource the reader consumes from code (Functions, Object Storage, SQL Database, KV Store, AI Inference) stays at the root of Platform Resources. So does a standalone service (Edge DNS, Data Stream, Orchestrator). A feature is a page inside its Platform Resource, never a dropdown. + +Quickstart carries the interface inside the page. A Platform Resource whose first run goes through Azion Console, the Azion CLI, or the API keeps one page and selects the interface with tabs. The slot then holds one row and one URL. The slot splits only when the interfaces cannot share one stage skeleton, and for an AI agent, whose path is driven by prompt and shares no stage with the others. Those pages group under Quickstart, with Console first; the group is a sidebar parent with a group hub, not an Overview. [Quickstart pages](/en/documentation/style-guide/content/quickstart/) holds the test. Platform onboarding, such as [Creating an account](/en/documentation/fundamentals/creating-account/) in Fundamentals, is a different thing. Quickstart is the slot of one Platform Resource. Onboarding is the platform entry point, and it belongs to no Platform Resource. @@ -64,7 +76,7 @@ Platform onboarding, such as [Creating an account](/en/documentation/fundamental - **The order mirrors adoption.** A slot never moves ahead of its stage. - **Pricing and Changelog close the section.** The reader consults them rather than passing through them. -- **The Required column decides what ships.** Every other slot exists only when real content fills it. The column applies to a section; a nested Platform Resource needs only its reference pages, plus a mechanism page when it has a mechanism to explain and a Quickstart when it has a setup of its own. +- **The Required column decides what ships.** Every other slot exists only when real content fills it. The column applies to a section. A nested Platform Resource always needs its reference pages. It also needs a mechanism page when it has a mechanism to explain, and a Quickstart when it has a setup of its own. - **Never add a slot to complete the pattern**, and never keep an empty one as a placeholder. - **The slot list is closed. Grow by splitting a slot the section already has:** Guides and tutorials into named task groups on the hub page, Features by surface. Quickstart grows inside its page, by interface tabs, and splits only when the stages cannot be shared. A fixed list is what lets the reader find the same slot in the same place in every section. @@ -89,7 +101,7 @@ Content that no single Platform Resource owns lives beside the Platform Resource - The page documents one Platform Resource: place it in that resource's section, in the slot its content type indicates. - The page explains the platform, accounts, or billing: it goes in Fundamentals. - The page diagnoses platform problems or reaches the support team: it goes in Support. -- The page builds a Use Case from the catalog: it is a [use case](/en/documentation/style-guide/content/use-cases/), and it goes in Use Cases, under the Solution area of its entry. +- The page explains a Use Case from the catalog: it is a [use case](/en/documentation/style-guide/content/use-cases/), and it goes in Use Cases, under the Solution area of its entry. - The page shows one Reference Architecture from the catalog, how Products and Platform Resources combine into a design: it goes in Architectures, under its Solution. - The page collects links for an area: it is a [navigation hub](/en/documentation/style-guide/content/navigation-hubs/), and it needs a real audience before it exists. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/multi-resource-guides.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/multi-resource-guides.mdx index 8fe41125e1..f548b7a1e5 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/multi-resource-guides.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/multi-resource-guides.mdx @@ -29,7 +29,7 @@ Do not write a multi-resource guide when: - One Platform Resource reaches the goal. Write a [how-to guide](/en/documentation/style-guide/content/how-to-guides/) in that Platform Resource's section. - The reader wants to understand the design rather than build it. Write an [architecture page](/en/documentation/style-guide/content/architecture/). -- The goal is a Use Case from the catalog. That is a use case, and it takes the same base form with an added scenario and a requirements table. +- The goal is a Use Case from the catalog. That is a [use case](/en/documentation/style-guide/content/use-cases/), which explains the design behind a scenario and links the guides that build it. ## Register @@ -132,7 +132,7 @@ To turn it on: Application Accelerator is enabled for the application. ``` -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx index d5e042b288..4610db1269 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx @@ -50,11 +50,11 @@ The default. Use it when the destinations differ from each other and the reader ### Shape 2: a table -Use it when the hub lists one homogeneous set and the reader chooses by type and freshness rather than by description. The Guides and tutorials slot is this shape, because every row is a how-to or a tutorial for the same Platform Resource and a per-row sentence would repeat the page title. +Use it when the hub lists one homogeneous set and the reader chooses by type and freshness rather than by description. The Guides and tutorials slot is this shape, because every row is a how-to or a tutorial for the same Platform Resource. A per-row sentence would only repeat the page title. - **Body**: one ``, no `##` headings and no groups. - **Columns**: name, type, last updated. -- **The table is generated, never typed.** A page appears when the guides catalog tags it with the Platform Resource, its type comes from the catalog, and its date from the page's last change, so the hub cannot fall out of step with the pages it lists. A resource's hub also lists the guides of the Platform Resources nested in it; a nested Platform Resource has no Guides and tutorials hub of its own. +- **The table is generated, never typed.** A page appears when the guides catalog tags it with the Platform Resource. Its type comes from the catalog, and its date from the page's last change. The hub therefore cannot fall out of step with the pages it lists. A resource's hub also lists the guides of the Platform Resources nested in it; a nested Platform Resource has no Guides and tutorials hub of its own. ### Shape 3: a group hub @@ -117,10 +117,10 @@ Its row in the navigation tree: - **No closing section and no other prose.** One sentence of orientation; explanation belongs in a [concept page](/en/documentation/style-guide/content/concept/). - **Make every link earn its place.** A hub is judged by what it leaves out; one that lists everything ranks nothing. - **Write descriptions that differentiate.** Say what this page gives that its neighbours do not. -- **Group when the list passes seven**, by what the reader is trying to do. A group hub does not group either: it lists the rows of its sidebar group, in sidebar order, however many there are. A table does not group: it sorts alphabetically by each row's navigation label, in the reader's language. The Platform Resources group of the root sidebar is the one exception: every Platform Resource in the order the reader adopts them, by decision, because grouping them by intent would restore the retired pillars. +- **Group when the list passes seven**, by what the reader is trying to do. A table does not group: it sorts alphabetically by each row's navigation label, in the reader's language. A group hub does not group either: it lists the rows of its sidebar group, in sidebar order, however many there are. The Platform Resources group of the root sidebar is the one exception: it lists every Platform Resource in the order the reader adopts them. That order is a decision, because grouping them by intent would restore the retired pillars. - **Pick the shape by what the reader compares.** Mixed destinations need a sentence each, so they take grouped links. One homogeneous set of pages, compared on type and freshness, takes the table. - **Give every sidebar group that holds pages a group hub.** A group with no page of its own leaves a breadcrumb crumb that opens nothing. The group hub is the one shape the sidebar decides, not the reader. -- **Never hand-write a table row.** A typed date is wrong the first time somebody forgets it, which is why this is the one place the guide allows a date outside a changelog. +- **Never hand-write a table row.** A typed date is wrong the first time somebody forgets it. The table's dates are generated, which is why [Numbers and units](/en/documentation/style-guide/formatting/numbers/#format-a-date-only-where-a-date-belongs) allows them outside a changelog. - **Register the page in the guides catalog.** A page the catalog does not list is missing from the hub. The first Platform Resource the catalog names for a page owns it and names its topic in the Guides section. - **Keep it in step with the section.** Update the hub in the same change that adds a page. - **Set `type: homepage` only on a card-grid hub.** Every other page omits the field. For more information, refer to [Frontmatter](/en/documentation/style-guide/conventions/frontmatter/). @@ -142,7 +142,7 @@ This section holds the guides to manage Object Storage buckets and objects, and - [Use a bucket as an application origin](/en/documentation/guides/application-development/data/use-bucket-as-origin/) - Serve the objects of a bucket from your own domain. ``` -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/overview.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/overview.mdx index 8723ec1928..c24d437b32 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/overview.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/overview.mdx @@ -38,8 +38,8 @@ Descriptive: 25 words per sentence, active voice, passive only when the actor is - **Definition block**, in three parts. First the Platform Resource: `**** is a that s .` That sentence names the resource, states its class, and stands on its own. The class is `Platform Resource`, on the Overview of a section and on the Overview of a nested Platform Resource alike, per [Documentation terminology](/en/documentation/style-guide/writing/terminology/#state-the-class-of-an-azion-element). The sentence never leans on a concept the reader has not met yet, as "runs that code" does. Then the concept: one or two sentences saying what the class of thing is, for a reader who has never used one, with any market term defined in place. Then one sentence naming the concrete jobs people use it for, in the reader's vocabulary, closing the block: `Use to handle A, run B, or serve C.` A bulleted benefit list is the weaker form of that sentence: it reads as a brochure and costs a screen. - **CTAs**: a primary `DocButton` labeled **Quickstart** and a secondary one labeled ` reference`. -- **The mechanism**: where a request, an event, or a job crosses more than two objects before the Platform Resource runs, that chain as a `mermaid` diagram, then a numbered walk of at most six items. Open with what the reader would otherwise assume wrong, and say in the same sentence what happens instead: `Creating a Function does not expose it: a request reaches it only through a Function Instance that a rule invokes.` -- **The specimen**: where the Platform Resource has a code artifact, a configuration object, or a request, one complete, minimal example of it, in full, right after the mechanism, or right after the CTAs when the page has no mechanism section. Two to four bullets name its parts, and one sentence says what prior knowledge transfers. A Platform Resource with no such artifact skips this section rather than inventing one. +- **The mechanism**: where a request, an event, or a job crosses more than two objects before the Platform Resource runs, that chain as a `mermaid` diagram. A numbered walk of at most six items follows the diagram. Open with what the reader would otherwise assume wrong, and say in the same sentence what happens instead: `Creating a Function does not expose it: a request reaches it only through a Function Instance that a rule invokes.` +- **The specimen**: where the Platform Resource has a code artifact, a configuration object, or a request, one complete, minimal example of it, in full. It sits right after the mechanism, or right after the CTAs when the page has no mechanism section. Two to four bullets name its parts, and one sentence says what prior knowledge transfers. A Platform Resource with no such artifact skips this section rather than inventing one. - **The resources**: only on a Platform Resource that has other Platform Resources nested in it. For each nested one, say what it does on this resource and when the reader turns it on, in one or two sentences, the first stating its class: ` is a Platform Resource that…`. Then point to where the reader goes to use it. This is what the reader needs to decide whether to open the nested Platform Resource, never its feature list. - **The boundaries**: one compressed bulleted block with bolded lead-ins — languages, APIs, frameworks, integrations, and the headline limits. One block, not one section per feature. - **Capability sections**: only for a capability that changes what the reader would build, three at most. A capability that is one sentence and a link belongs in the boundaries block or the router. @@ -110,10 +110,10 @@ Use to , , or . - **Tell a relation between two Platform Resources forward.** The one that makes the connection is the subject, and the sentence runs in the order things happen: `An Application receives the requests of a Workload once that Workload's deployment sets that Application.` The sentence `An Application receives the requests of the Workloads whose deployment sets it.` starts at the end and leaves two pronouns that point backwards. In Brazilian Portuguese, the verb takes its object in full: `define essa Application`, never `a define`. - **Choose the concept with care.** Several Azion elements do different things under one name. When one market concept fits everything the Platform Resource does, explain that concept. When none does, explain each thing in a sentence. - **Name the Platform Resource that provides a concept.** When another Platform Resource provides one of those things, the sentence that explains the market term names its instance right after the term, and keeps the explanation: `A serverless function is a Function, code run on demand at each request, with no server for you to provision.` -- **Cut from the definition block what the reader does not need.** Four kinds of sentence go: background the Platform Resource does not change, such as how a registry delegates a domain; the step the reader already assumes, such as a proxy opening its own connection to the origin; a point the block already made; and a contrast with something the page does not cover, such as `A log is the opposite view.` +- **Cut from the definition block what the reader does not need.** Four kinds of sentence go. The first is background the Platform Resource does not change, such as how a registry delegates a domain. The second is a step the reader already assumes, such as a proxy that opens its own connection to the origin. The third is a point the block already made. The fourth is a contrast with something the page does not cover, such as `A log is the opposite view.` - **A use says what this Platform Resource adds.** The uses sentence names the jobs this Platform Resource does that another one does not. On Functions, the use is "block requests with your own logic", because Firewall already blocks requests by rule. A security Platform Resource names the public standard its pages document, such as the OWASP Top 10. - **Name the Platform Resource in the first sentence, and never open on the problem space.** A concept sentence explains a mechanism. A sentence about how important the problem is explains nothing. -- **Organize by the reader's questions, not by your feature list.** The sections answer, in order: what does the Azion Platform Resource do, what is the class of thing, how does it get called, what am I writing, which Products it hosts, what can it do and where does it stop, where do I go now. An outline that reproduces the Platform Resource's feature list is a catalog: it answers "what do we sell" instead of "what am I deciding". +- **Organize by the reader's questions, not by your feature list.** The sections answer seven questions, in order. The first three are what the Azion Platform Resource does, what the class of thing is, and how it gets called. The next three are what I am writing, which Products it hosts, and what it can do and where it stops. The last is where I go now. An outline that reproduces the Platform Resource's feature list is a catalog: it answers "what do we sell" instead of "what am I deciding". - **The questions shape the sections; they never become the headings.** A heading is a short noun phrase, never a question: `Function structure`, not `What a function looks like`. - **Draw the diagram from the documented sequence.** A diagram of a sequence the documentation already states in prose is a change of notation, not a new fact. Every node and every arrow matches a step the Platform Resource performs, and the numbered walk carries the meaning if the figure does not render. - **Send the reader to the [Quickstart](/en/documentation/style-guide/content/quickstart/)**, in the CTAs and again in the router. @@ -121,7 +121,7 @@ Use to , , or . ## Examples -This excerpt of the **Functions** overview shows the definition block in its three parts and the specimen, and leaves out the mechanism. The first sentence names the Platform Resource, states its class, and says what it does on Azion; the next ones explain what a function is to a reader who has never used one; the uses sentence closes the block; the specimen shows the artifact instead of describing it: +This excerpt of the **Functions** overview shows the definition block in its three parts and the specimen, and leaves out the mechanism. The first sentence names the Platform Resource, states its class, and says what it does on Azion. The next ones explain what a function is to a reader who has never used one. The uses sentence closes the block, and the specimen shows the artifact instead of describing it: ```mdx **Functions** is a Platform Resource that runs JavaScript code on Azion's distributed infrastructure, inside the request path of an application or a firewall. A function is code that runs when a request arrives: you write a handler that receives the request and returns a response, and the platform starts it on demand and stops it when the response is sent, so there is no server to provision or scale. That model is called [serverless](https://www.azion.com/en/learning/serverless/what-is-serverless/). Use Functions to build APIs, manipulate request and response headers, apply logic from request metadata, or block traffic before it reaches your application. @@ -161,7 +161,7 @@ import DocCard from '@aziontech/webkit/doc-card' ``` -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/quickstart.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/quickstart.mdx index 2a4aef6733..64c568496c 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/quickstart.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/quickstart.mdx @@ -144,11 +144,11 @@ To in Azion Console: ## Rules - **State the object chain before the first step.** Name every object the reader creates and what it must be linked to, in order. A quickstart that lists clicks without the composition model leaves the reader unable to repeat the result with different objects. -- **The reader selects the interface once, under the prerequisites heading.** The first thing under `## Prerequisites` is a `` block carrying the `tab.*` slots and the prerequisite panels. Each stage carries its own block of the same store, holding only `panel.*` slots: it renders the same strip above its panels, so the reader can switch at any stage without scrolling back. The stage heading and the sentence that introduces the stage stay outside the block, so the page keeps one table of contents entry per stage. Console first. The mechanics are in [Components](/en/documentation/style-guide/components/). +- **The reader selects the interface once, under the prerequisites heading.** The first thing under `## Prerequisites` is a `` block carrying the `tab.*` slots and the prerequisite panels. Each stage carries its own block of the same store, with only `panel.*` slots. That block renders the same strip above its panels, so the reader can switch at any stage without scrolling back. The stage heading and the sentence that introduces the stage stay outside the block, so the page keeps one table of contents entry per stage. Console first. The mechanics are in [Components](/en/documentation/style-guide/components/). - **Write the prerequisites per interface.** Each prerequisite panel lists everything that interface needs, the shared items first and then its own, so a reader never reads a requirement that is not theirs. Drop the qualifier that names the interface once the panel carries the item. - **The tab selects the interface, not the path.** Every panel creates the same objects, in the same stages, to the same verified outcome, and only the mechanics differ. This is why a quickstart uses tabs where a [tutorial](/en/documentation/style-guide/content/tutorials/) does not: the reader still chooses nothing about what they build. - **Give every block the same `sharedStore="interface"` and the same panel keys.** The one selection then governs every stage, and follows the reader to the next page. A stage that omits an interface the selector offers opens on its own first panel, which silently moves the reader to another interface mid-page. -- **Write each panel to be read alone.** The lead-in names the interface, and the outcome sentence belongs inside the panel: Azion Console shows a list where the API returns a response body. Never write "as you selected above": the selection does follow the reader to the next page, but a page that does not offer that interface opens on its own first panel. +- **Write each panel to be read alone.** The lead-in names the interface, and the outcome sentence belongs inside the panel: Azion Console shows a list where the API returns a response body. Never write "as you selected above". The selection does follow the reader to the next page. A page that does not offer that interface, though, opens on its own first panel. - **Open every panel with the interface's name as a heading.** The heading sits one level below the stage and repeats the tab label: `### Console`, `### CLI`, `### API`. A reader who has scrolled past the selector still sees which interface the steps belong to. Panel headings stay out of the table of contents. Each one links to its stage with its interface selected, `?interface=api#create-a-database`, so a shared link opens the right stage on the right tab. - **Split into separate pages when the stages cannot be shared.** Interfaces that need different stages, or a different object chain, are different paths rather than different mechanics. Give each its own page, titled ` quickstart using `, under one Quickstart group in the sidebar, Console first. The group is a menu parent with a group hub as its breadcrumb landing, not an Overview. Name the siblings in one line under the opening move: `Prefer the CLI? Refer to [ quickstart using the Azion CLI](/path/).` - **An AI-agent first run is always its own page.** A path the reader drives by prompt shares no stage with a click path or a command. Title it ` quickstart using an AI agent`, connected through the [Azion MCP server](/en/documentation/agent-setup/), and name it in the sibling line. @@ -189,7 +189,7 @@ To run a Function, you create and connect these objects: The chain tells the reader why four objects exist before a single request reaches their code. Without it, the steps read as unexplained clicks. -This excerpt shows the prerequisites of the same page, which carry the strip, then one stage. The strip is declared once; the stage block carries panels alone. The stage heading and the sentence that frames the stage sit outside the block, and each panel opens with the interface's heading, then carries its own lead-in and its own outcome sentence: +This excerpt shows the prerequisites of the same page, which carry the strip, then one stage. The strip is declared once; the stage block carries panels alone. The stage heading and the sentence that frames the stage sit outside the block. Each panel opens with the interface's heading, then carries its own lead-in and its own outcome sentence: ```mdx ## Prerequisites @@ -255,7 +255,7 @@ The command returns the Function's ID, which the next stage uses to instantiate Both panels reach the same object, so the stage heading and the object chain hold for either reader. -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/reference.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/reference.mdx index e711f00720..55632818bc 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/reference.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/reference.mdx @@ -109,8 +109,8 @@ Support can raise the limits marked raisable. Contact . - **Never invent a limit or a plan name.** Take both from the pricing page, the plans agreement, or the team that owns the Platform Resource. A value you cannot confirm is not published: narrow the table to the dimensions you can confirm. - **Never restate a price.** Amounts, quotas sold by the unit, and billing metrics live on the pricing page alone. Link it; do not copy it. - **No marketing.** Say what it does and where it stops. -- **A CLI command page has its own shape.** A one-line summary, then one `##` per command or subcommand, named in words, such as `Logs cells` or `List`, and never the command itself. A page about one command with no subcommands keeps a single `## Usage` section, and so does the parent command of a page whose subcommands each get their section. Each section opens with a sentence on what the command does, then the call with only its required flags and a placeholder for each value the reader supplies, then a `Flags` heading one level down that holds the flag table. A worked example with real values and its output can follow the call. Only notes about a flag sit under `Flags`; an example, its output, and a note about the command go above it. A command with no flags of its own shows the bare call and no `Flags` heading. -- **An API reference section has the same shape.** A function, method, type, or dataset is a section named in words, whose first sentence starts with the identifier. A runnable sample, with its output, comes first. The signature follows it, just before the table, because the signature is the contract: it shows the types, which arguments are optional, and which values are fields of one object, as in `createClient({ token, options })`. The table sits under a heading of its kind, one level below the section: `Parameters`, `Properties`, `Fields`, `Arguments`, `Methods`, or `Members`. A note about one row stays under the table; a note about the call goes above it. A type that is defined by a code block, such as a union of string values, keeps the block: it is the reference, not a signature. +- **A CLI command page has its own shape.** A one-line summary, then one `##` per command or subcommand, named in words, such as `Logs cells` or `List`, and never the command itself. A page about one command with no subcommands keeps a single `## Usage` section, and so does the parent command of a page whose subcommands each get their section. Each section opens with a sentence on what the command does. The call follows, with only its required flags and a placeholder for each value the reader supplies. Last, a `Flags` heading one level down holds the flag table. A worked example with real values and its output can follow the call. Only notes about a flag sit under `Flags`; an example, its output, and a note about the command go above it. A command with no flags of its own shows the bare call and no `Flags` heading. +- **An API reference section has the same shape.** A function, method, type, or dataset is a section named in words, whose first sentence starts with the identifier. A runnable sample, with its output, comes first. The signature follows it, just before the table, because the signature is the contract. It shows the types, which arguments are optional, and which values are fields of one object, as in `createClient({ token, options })`. The table sits under a heading of its kind, one level below the section: `Parameters`, `Properties`, `Fields`, `Arguments`, `Methods`, or `Members`. A note about one row stays under the table; a note about the call goes above it. A type that is defined by a code block, such as a union of string values, keeps the block: it is the reference, not a signature. - **Table headings are fixed, not container headings.** `Flags` and the six kinds above are the headings every reference page repeats over its tables, so a review never reports them as headings that name a kind of thing. ## Examples @@ -164,7 +164,7 @@ Support can raise the limits marked raisable. Contact the [technical support tea The missing column is the point. The breakdown by plan for these numbers was not confirmed, so the table has no plan column rather than an invented one. -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/troubleshooting.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/troubleshooting.mdx index 846194c496..2a678b2bbb 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/troubleshooting.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/troubleshooting.mdx @@ -147,7 +147,7 @@ To find the rule and allow the legitimate requests with WAF Tuning: The new allowed rule appears in the **Allowed Rules** tab of the **WAF Rules** page. The WAF no longer blocks the requests that match the allowed rule. ``` -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/tutorials.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/tutorials.mdx index 13d79354ac..bd649a94e2 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/tutorials.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/tutorials.mdx @@ -105,7 +105,7 @@ You will create <...>, configure <...>, and deploy <...>. ## Rules - **Keep the contract.** You choose every option: no branching, no "depending on your needs". Every step shows a visible result, and you have run every command. -- **No ``.** Tabs are a branch, and tutorials do not branch. A task that genuinely needs three interfaces is a [how-to guide](/en/documentation/style-guide/content/how-to-guides/). The one exception is a [Quickstart page](/en/documentation/style-guide/content/quickstart/), where a tab selects the reader's interface and not the path: every panel builds the same objects, in the same stages, to the same outcome. +- **No ``.** Tabs are a branch, and tutorials do not branch. A task that genuinely needs three interfaces is a [how-to guide](/en/documentation/style-guide/content/how-to-guides/). The one exception is a [Quickstart page](/en/documentation/style-guide/content/quickstart/), where a tab selects the reader's interface and not the path. Every panel there builds the same objects, in the same stages, to the same outcome. - **Do not explain.** One sentence and a link when a concept is genuinely required. Keep asides rare. - **Make every screenshot earn its place.** One image for a result words cannot show, never a shot of every screen the reader passes. - **Link out for third-party services.** Name the vendor's step; do not document their interface. @@ -147,7 +147,7 @@ To check the creation status, send `GET` requests to the same endpoint until `st The database is ready when `status` is `created`. ``` -## Related +## Related resources diff --git a/apps/docs/src/content/docs/en/pages/style-guide/content/use-cases.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/use-cases.mdx index ae3317c944..1dd2e6e0a3 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/content/use-cases.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/content/use-cases.mdx @@ -13,9 +13,9 @@ import DocItem from '@aziontech/webkit/doc-item' ## Purpose -A use-case page explains one entry of the Use Case catalog as a design: what the scenario needs, which resources meet it, and why the design takes the shape it does. The entry gives the page its title, its scenario, its Products, and the reference architectures it can build. The page never coins a use case of its own. The catalog is maintained by Azion. A writer who needs an entry, or finds one wrong, asks for it before writing the page. The request goes through the repository's issue templates, or through the catalog's owner inside Azion. The reader arrives with a situation, not a task: a storefront that slows down during a sale, a live event that has to reach one more region. +A use-case page explains one entry of the Use Case catalog as a design. It says what the scenario needs, which resources meet it, and why the design takes the shape it does. The entry gives the page its title, its scenario, its Products, and the reference architectures it can build. The page never coins a use case of its own. The catalog is maintained by Azion. A writer who needs an entry, or finds one wrong, asks for it before writing the page. The request goes through the repository's issue templates, or through the catalog's owner inside Azion. The reader arrives with a situation, not a task: a storefront that slows down during a sale, a live event that has to reach one more region. -A use case is theory, not a procedure. It carries what a reader needs to understand and decide: the Products the scenario requires, the architecture, how each part of the design works and the reason behind it, and the metrics that show it working. The values each configuration takes, every procedure, every command, and every check live in the guides the page links. Each guide section that applies part of the design names the use case and holds the values it takes there, so an implementer, often an agent, builds it from those guides without asking a question. +A use case is theory, not a procedure: it applies the [explanation](/en/documentation/style-guide/content/concept/) base form. It carries what a reader needs to understand and decide. Those are the Products the scenario requires, the architecture, how each part of the design works and why, and the metrics that show it works. The values each configuration takes, every procedure, every command, and every check live in the guides the page links. Each guide section that applies part of the design names the use case and holds the values it takes there. An implementer, often an agent, then builds the design from those guides without asking a question. Use cases live in the Use Cases section, never inside a Platform Resource section, under the Solution area of their catalog entry. The area's label is the Solution name. The guides a use case links live in the Guides section. @@ -44,7 +44,7 @@ Use cases live in the Use Cases section, never inside a Platform Resource sectio ## Register -Descriptive: 20 words per sentence, active voice, present tense. A use case states what each part of the design does and why. The imperative belongs to the guides it links. Tone: precise, plain, businesslike, sober. [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/) holds the rules. +Descriptive: 25 words per sentence, active voice, present tense. A use case states what each part of the design does and why. The imperative belongs to the guides it links. Tone: precise, plain, businesslike, sober. [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/) holds the rules. ## Structure @@ -53,11 +53,11 @@ Descriptive: 20 words per sentence, active voice, present tense. A use case stat - **Scenario**: three to five sentences from the catalog entry's Scenario. They name the actor, the workload and the situation it is in, what this page sets up, and the measurable result. Followed by one line stating what the use case does not cover, the entry's own exclusion. - **Prerequisites**: a `## Prerequisites` section, each item a link. The first item is the Azion account, with an inline link to the sign-up page: `An Azion account. If you do not have one, [create an account](https://console.azion.com/signup).` The other items name what the reader must already have, such as an origin, a domain, or a repository. Tools, tokens, and the example values belong to the guides. - **Required products**: the requirements table. One row per requirement, naming the technical need, the Product that meets it, and the page that documents it. The Product column holds the Products of the catalog entry. A dependency the Platform Resource documentation confirms and the entry omits goes in the table too, and the gap is reported to the catalog. The technical need names the Platform Resource the reader configures. -- **Reference architecture**: a `## Reference architecture` section. It opens by naming which of the entry's Reference Architectures the page builds, then holds a legend of one or two sentences, a `mermaid` diagram, a numbered `### Dataflow` directly under it, and, after the list, what the design shows that no step says, a `### Platform Resources` list naming each Platform Resource and Feature with its role in this design, and `### Other designs for this use case`, one bullet per other Reference Architecture of the entry. -- **How the design works**: a `## How the design works` section that opens with one sentence naming what it explains, then one `###` per part of the design that is specific to this use case, four at most, each a noun phrase such as `### The catalog cache`. Each explains what that part does and why: the reasoning, the rule logic, and a diagram when the logic branches. A value appears only inside the sentence that gives its reason. It holds no values table, no step, no check, and no link line to a procedure. A part met by a guide's defaults gets no subsection: the requirements table links the guide that documents it. +- **Reference architecture**: a `## Reference architecture` section. It opens by naming which of the entry's Reference Architectures the page builds. Then it holds a legend of one or two sentences, a `mermaid` diagram, and a numbered `### Dataflow` directly under it. After the list comes what the design shows that no step says. Then a `### Platform Resources` list names each Platform Resource and Feature with its role in this design. Last, `### Other designs for this use case` holds one bullet per other Reference Architecture of the entry. +- **How the design works**: a `## How the design works` section that opens with one sentence that names what it explains. Then comes one `###` per part of the design that is specific to this use case, four at most, each a noun phrase such as `### The catalog cache`. Each explains what that part does and why: the reasoning, the rule logic, and a diagram when the logic branches. A value appears only inside the sentence that gives its reason. It holds no values table, no step, no check, and no link line to a procedure. A part met by a guide's defaults gets no subsection: the requirements table links the guide that documents it. - **Measuring results**: a `## Measuring results` section naming the metrics that show the setup working, and where to read each one. - **Best practices**: a `## Best practices` section holding recommendations about the design and the reasoning behind each. -- **Guides in this use case**: a `## Guides in this use case` closing, a `DocCardGroup` with one card per guide that holds this use case's values or checks: the title, the link, and what the guide does for this use case as the card copy. +- **Guides in this use case**: a `## Guides in this use case` closing, a `DocCardGroup` with one card per guide that holds this use case's values or checks. Each card carries the title, the link, and, as its copy, what the guide does for this use case. **Optional components** @@ -69,7 +69,7 @@ The sections keep this order. What governs the page is proportion, not length. T - **Scenario, prerequisites, demo, and the guide cards stay brief.** Each orients and hands off. A scenario that runs past a couple of paragraphs is selling. - **Measurement and best practices sit between the two.** Each carries real content, a signal to watch or a reason, and neither is a place to expand. -The bound that keeps a use case honest is the four-subsection cap on `## How the design works`, not a length. A sentence that needs a table, a step, or a command has put a guide's content on the wrong page: it moves to the guide section that applies it, and the reason stays here. +The bound that keeps a use case honest is the four-subsection cap on `## How the design works`, not a length. A sentence that needs a table, a step, or a command has put a guide's content on the wrong page. That content moves to the guide section that applies it, and the reason stays here. ## Template @@ -175,7 +175,7 @@ flowchart TD ## Rules - **Explain the design; leave the doing to the guides.** Every choice carries its reason, and nothing says "depending on your setup". The reader may be an agent, and an agent cannot resolve an ambiguity by asking. -- **Keep values, steps, checks, and code off the page.** No fenced block other than the diagram, no table of settings, no ``, no ``, no verification, and no command. The values a part of the design takes go to the guide section that applies it, under a line that names the use case, and the expected results go to that guide's confirm section. When no guide holds the procedure, extend a guide or write a new [how-to guide](/en/documentation/style-guide/content/how-to-guides/) first, then link it. +- **Keep values, steps, checks, and code off the page.** No fenced block other than the diagram, no table of settings, no ``, no ``, no verification, and no command. The values a part of the design takes go to the guide section that applies it, under a line that names the use case. The expected results go to that guide's confirm section. When no guide holds the procedure, extend a guide or write a new [how-to guide](/en/documentation/style-guide/content/how-to-guides/) first, then link it. - **Narrow the scenario to one buildable setup.** State it as `A that configures so that .` If the sentence needs an "and also", the entry is too wide for one page. Write the first setup and report the width to the catalog. Do not coin a second use case. - **Start from the requirements table.** Every row is a requirement you have confirmed against the Platform Resource documentation. A requirement you cannot confirm does not go in the table. - **Explain what is specific to this use case. The guides carry how.** The reasons the scenario changes a setting stay on the page. The values and the procedure that applies them live in the guide, which names this use case. @@ -184,7 +184,7 @@ flowchart TD - **Draw the request and the way back.** In the reference architecture flowchart, solid arrows (`-->`) carry the request, and dotted arrows (`-.->`) carry the response. A flow that runs apart from any request, such as a purge or a log stream, takes thick arrows (`==>`). A response arrow starts where the response starts: Cache on a hit, the firewall on a block, the origin on a miss. It passes through a node only when that node acts on the response, such as Cache storing a copy. A response the application handles returns through the application, which delivers it. A response the firewall gives goes straight to the client, because the application never receives that request. A read gets its way back too: a dotted arrow from the data store to the node that read it, labeled with what it returns. The legend above the diagram names what each arrow style carries. - **Number every arrow of the reference architecture diagram by its dataflow step.** Each arrow label starts with the number of the `### Dataflow` item it belongs to, such as `2, 4. miss`. Every item has at least one arrow, and every arrow has an item. The way back belongs to the step it answers, so it never adds a step. A diagram in `## How the design works` follows the list under it instead. - **Put the dataflow right under the diagram.** The legend goes above the diagram, and `### Dataflow` follows the fence with nothing between them, so the arrows and the steps they number are on screen together. A sentence that retells a step adds nothing and is cut. What the design shows and no step says, such as which part sits in the failure flow, goes after the list. -- **Give each role one shape.** The client is a stadium (`(["Visitor"])`), anything on Azion, a Product or a Platform Resource, is a rectangle (`["application"]`), a data store is a cylinder (`[("KV Store")]`), and a system outside Azion is a subroutine (`[["commerce platform"]]`). Shape and line style carry every distinction, never color. +- **Give each role one shape.** The client is a stadium (`(["Visitor"])`). Anything on Azion, a Product or a Platform Resource, is a rectangle (`["application"]`). A data store is a cylinder (`[("KV Store")]`), and a system outside Azion is a subroutine (`[["commerce platform"]]`). Shape and line style carry every distinction, never color. - **Run every flowchart top to bottom** (`flowchart TD`), a chain of steps included. A chain drawn left to right grows wider than the column and shrinks its labels to fit. - **Open every diagram with the shared `init` line**, as the template shows. It lays the diagram out with ELK, gives the labels room, and shrinks a diagram wider than the column to fit it. When the client does not render at the top, add an `elk` object right after `"layout": "elk",` with ELK's model-order options, so the declaration order decides the layers: `"cycleBreakingStrategy": "MODEL_ORDER"`, or `"preset": "modelOrder", "keepEntryNodeOnTop": true`. - **Measure, do not verify.** The one-time check that a setup is correct lives in the guides' confirm sections. The page names the ongoing signals that show the design still works. @@ -230,11 +230,11 @@ In the [Build e-commerce storefronts](/en/documentation/use-cases/build-and-run- Application Accelerator is not among the catalog entry's Products. The Rules Engine reference confirms that the **Bypass Cache** behavior requires it, so the row carries it and the gap goes back to the catalog. -## Related +## Related resources - The same base form, without the business frame. + The how-to kind for a goal that crosses Platform Resources, without a catalog entry. The kind to write when no setting takes a value of its own. The kind that holds a use case's values and checks, and the one to write when no guide holds a procedure. Where use cases sit, and why they live outside a Platform Resource section. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/conventions/bilingual.mdx b/apps/docs/src/content/docs/en/pages/style-guide/conventions/bilingual.mdx index 35b0152274..8527c23895 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/conventions/bilingual.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/conventions/bilingual.mdx @@ -12,7 +12,7 @@ permalink: /documentation/style-guide/conventions/bilingual/ The documentation publishes every page in US English and in Brazilian Portuguese. US English is the source of truth. Write the Brazilian Portuguese page on top of the finished US English page, not in parallel with it. The structure of the Brazilian Portuguese page follows the US English page, and a change to the US English page creates matching work on the Brazilian Portuguese page. -To write or update a Brazilian Portuguese page, open the US English page first. If the US English page does not exist, write it first: a Brazilian Portuguese page written first has no source, and the US English page that follows becomes a translation of a translation. +To write or update a Brazilian Portuguese page, open the US English page first. If the US English page does not exist, write it first. A Brazilian Portuguese page written first has no source. The US English page that follows it becomes a translation of a translation. ## Pair the versions by namespace @@ -68,8 +68,8 @@ The structural rules in [Sentence structure](/en/documentation/style-guide/writi Six rules cover most of the work on a Brazilian Portuguese page: - Do not translate generic technical terms: `data center`, `serverless`, `template`, `compliance`, `on-premise`, `authoritative DNS`. The strings `edge` and `edge computing` stay untranslated where they already appear, but new text does not introduce them. -- Do not translate Platform Resource names or other Azion names: **Applications**, **Functions**, **Firewall**, **Azion Platform**, **Azion Marketplace**. The instance keeps the name too: `uma Function`, `as suas Applications`. Never replace a name with a Portuguese description of it: `firewall de aplicação web` for Web Application Firewall, `gerenciamento de bots` for Bot Manager, `armazenamento de objetos` for Object Storage, and `funções` for Functions each hide the name the reader looks for. -- Apply the substitutions: `aplicação`, not `aplicativo`, only for the customer's own software, because the instance created in Azion is an `Application`; `rede distribuída`, not `borda`, when translating existing text; `performance`, not `desempenho`. New Brazilian Portuguese text that names where the platform runs writes `infraestrutura distribuída`. +- Do not translate Platform Resource names or other Azion names: **Applications**, **Functions**, **Firewall**, **Azion Platform**, **Azion Marketplace**. The instance keeps the name too: `uma Function`, `as suas Applications`. Never replace a name with a Portuguese description of it, because the description hides the name the reader looks for. Examples are `firewall de aplicação web` for Web Application Firewall, `gerenciamento de bots` for Bot Manager, `armazenamento de objetos` for Object Storage, and `funções` for Functions. +- Apply the substitutions. Write `aplicação`, not `aplicativo`, only for the customer's own software, because the instance created in Azion is an `Application`. Write `rede distribuída`, not `borda`, when you translate existing text, and `performance`, not `desempenho`. New Brazilian Portuguese text that names where the platform runs writes `infraestrutura distribuída`. - Write the phrase a Portuguese reader uses, not the English sentence word for word: `experimentaram` becomes `experienciaram` or `vivenciaram`, `nenhum servidor sozinho carrega toda ela` becomes `nenhum servidor fica sobrecarregado`, and `nunca consulta uma API` becomes `sem a necessidade de consultar uma API`. - Write titles in sentence case: capitalize the first word and proper nouns only. - Localize aside labels: `:::note[nota]`, `:::tip[dica]`, `:::caution[Atenção]`, `:::danger[perigo]`. The casing follows the repository usage: `nota`, `dica`, and `perigo` in lowercase, `Atenção` capitalized. A US English label on a Brazilian Portuguese page is a visible defect. @@ -80,11 +80,12 @@ The full list of terms that stay in US English is in [Documentation terminology] Three recurring elements translate the same way on every page. Do not improvise a new form for them. -Three section names have fixed Brazilian Portuguese forms: +Four section names have fixed Brazilian Portuguese forms: - `## Prerequisites` becomes `## Pré-requisitos`. - `## Next steps` becomes `## Próximos passos`. - `## Related resources` becomes `## Recursos relacionados`. +- `## Guides in this use case` becomes `## Guias deste caso de uso`. The standard link sentences have fixed forms, and the verb is `consulte`: diff --git a/apps/docs/src/content/docs/en/pages/style-guide/formatting/code.mdx b/apps/docs/src/content/docs/en/pages/style-guide/formatting/code.mdx index 32d39529ec..b94c8dd20d 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/formatting/code.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/formatting/code.mdx @@ -58,15 +58,15 @@ One sentence before the block states what the code does. A bare code block is a ## Format JSON over several lines -Show JSON indented with two spaces, one key per line, never on a single line. A response, an error body, or a logged object on one line forces the reader to scroll sideways and hides its structure. A block that holds only JSON takes the `json` tag. When JSON follows text in the same output, such as HTTP headers before a response body or a label before a logged object, keep the text as it is and format only the JSON, under a `text` tag. Formatting changes the layout only: keep every key, value, and their order. +Show JSON indented with two spaces, one key per line, never on a single line. A response, an error body, or a logged object on one line forces the reader to scroll sideways and hides its structure. A block that holds only JSON takes the `json` tag. JSON can follow text in the same output, such as HTTP headers before a response body or a label before a logged object. Keep that text as it is, and format only the JSON, under a `text` tag. Formatting changes the layout only: keep every key, value, and their order. -Two outputs keep their single line, because the line is what the reader compares or searches for: a row of a table that a command prints, such as `Modules: {...}` in a `describe` output, and an error message that ends in a JSON list, such as `Error: failed to create the Firewall Rule: ["..."]`. +Two outputs keep their single line, because the line is what the reader compares or searches for. One is a row of a table that a command prints, such as `Modules: {...}` in a `describe` output. The other is an error message that ends in a JSON list, such as `Error: failed to create the Firewall Rule: ["..."]`. JSON Lines keeps one value per line by definition. A body or a file that carries one JSON value per line, such as an NDJSON request body, takes the `jsonl` tag, and each value stays on its own line. ## Tag the language, and name a file only when there is one -The language tag on a fence drives the highlighting and names the language in the bar above any block of two or more lines: `bash` reads `Shell`, `json` reads `JSON`, `jsonl` reads `JSON Lines`. Give every fence a tag, and `text` to output that has no language. A one-line block shows no line numbers, and no bar unless it has a `title`. +The language tag on a fence drives the highlighting. It also names the language in the bar above any block of two or more lines: `bash` reads `Shell`, `json` reads `JSON`, `jsonl` reads `JSON Lines`. Give every fence a tag, and `text` to output that has no language. A one-line block shows no line numbers, and no bar unless it has a `title`. Add `title="..."` only when the block is a file the reader saves, such as `title="azion.config.js"`. The file name takes the language's place in the bar. The props are in [Components](/en/documentation/style-guide/components/). diff --git a/apps/docs/src/content/docs/en/pages/style-guide/formatting/headings.mdx b/apps/docs/src/content/docs/en/pages/style-guide/formatting/headings.mdx index 9dc907bff5..bc1b2a2a3f 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/formatting/headings.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/formatting/headings.mdx @@ -71,7 +71,7 @@ Two mechanics follow. A string that ends in a period loses it, because a heading ## Name a section, never its command or field -A section heading names what the section covers, in words. It is never only the command the section documents or the configuration field it describes: `Logs cells` heads the section about `azion logs cells`, and `Network lists` heads the section about the `networkList` key of `azion.config`. A heading that is only a command or a field reads as a string to type, in the page outline and in a search result, and it tells a reader who does not know the command nothing about the section. +A section heading names what the section covers, in words. It is never only the command the section documents or the configuration field it describes. `Logs cells` heads the section about `azion logs cells`, and `Network lists` heads the section about the `networkList` key of `azion.config`. A heading that is only a command or a field reads as a string to type, in the page outline and in a search result. It tells a reader who does not know the command nothing about the section. | Incorrect | Correct | | --- | --- | @@ -80,11 +80,11 @@ A section heading names what the section covers, in words. It is never only the | `getWithMetadata` | `Get with metadata` | | `workloadMetrics` | `Workload metrics` | -The rule covers API references too. A function, method, type, or dataset is named in words, and the first sentence of its section starts with the identifier, so a reader who searches the page for `getWithMetadata` still lands on the section: `` `getWithMetadata` reads a key and returns the value together with its metadata. `` +The rule covers API references too. A function, method, type, or dataset is named in words, and the first sentence of its section starts with the identifier. A reader who searches the page for `getWithMetadata` then still lands on the section: `` `getWithMetadata` reads a key and returns the value together with its metadata. `` A type name drops the `Azion` prefix that the library puts on its types, because the page already says whose types they are: `AzionSQLClient` becomes `SQL client`. -In Portuguese, the name of a method or a type stays in English, as developers say it: `Get with metadata`, `SQL client`. The name of a function that does a task and the name of a dataset are translated: `Criar um banco de dados`, `Métricas de workload`. A CLI subcommand follows the same split: one that does a task is translated, such as `Criar` or `Inicializar`, and one that names a thing keeps its name, such as `Logs HTTP`. +In Portuguese, the name of a method or a type stays in English, as developers say it: `Get with metadata`, `SQL client`. The name of a function that does a task and the name of a dataset are translated: `Criar um banco de dados`, `Métricas de workload`. A CLI subcommand follows the same split. One that does a task is translated, such as `Criar` or `Inicializar`, and one that names a thing keeps its name, such as `Logs HTTP`. A product or tool name is a name, not an identifier, and stays as it is: `GraphiQL`, `GeoIP`, `OpenNext`. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/formatting/numbers.mdx b/apps/docs/src/content/docs/en/pages/style-guide/formatting/numbers.mdx index c1072962b5..c82deb4fc7 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/formatting/numbers.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/formatting/numbers.mdx @@ -49,7 +49,12 @@ Write `first` and `second` as words. In a numeral, write `1st`, never `1stly` or ## Format a date only where a date belongs -Dates appear in changelogs and nowhere else, which [Word choice](/en/documentation/style-guide/writing/word-choice/) states as a rule. A date anywhere else ages the page. +A date ages the page it sits on, so hand-written prose carries none, as [Word choice](/en/documentation/style-guide/writing/word-choice/) requires. A date belongs in four places only: + +- **A changelog**, where every entry is a date. +- **A generated date**: the last-updated line of every page header and the last-updated column of a Guides and tutorials hub. A build step writes it, so it never goes stale. +- **A dated agreement**, which records what was true on the day of publication, as [Documentation terminology](/en/documentation/style-guide/writing/terminology/#keep-historical-names-in-historical-documents) explains. +- **The shutdown date of API v3**, which appears only in the `versionDeprecated` snippet and on API v4 Migration, as [Components](/en/documentation/style-guide/components/#version-notices) sets out. Where a date is allowed, spell the month out and order it month, day, year: `July 10, 2026`. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/how-we-docs/docs-as-code.mdx b/apps/docs/src/content/docs/en/pages/style-guide/how-we-docs/docs-as-code.mdx index 6d632d58e5..18b453efd2 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/how-we-docs/docs-as-code.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/how-we-docs/docs-as-code.mdx @@ -34,7 +34,7 @@ The checks run in GitHub Actions on each pull request against `main`, in three w | Code quality | ESLint, Prettier, and Stylelint on the files the pull request changes, and `astro check` | A lint or format error in a changed file, and more type errors than the baseline | | Build | `astro build`, then `test:frontmatter` | A page that does not compile, and a `permalink` that is missing, malformed, or duplicated, or a duplicated `namespace` | -**Internal links** builds the site and runs the link checker. The checker follows internal links only. It reports a link to a page or a fragment that does not exist, a link to a redirect page instead of the canonical URL, an absolute URL where a relative one belongs, and a link to a page in the other language. The vague-text check covers every link, internal or external: it reports link text such as "here" or "read more". +**Internal links** builds the site and runs the link checker. The checker follows internal links only. It reports a link to a page or a fragment that does not exist, and a link to a redirect page instead of the canonical URL. It also reports an absolute URL where a relative one belongs, and a link to a page in the other language. The vague-text check covers every link, internal or external: it reports link text such as "here" or "read more". **Design system adoption** runs the design system lint rules over the UI and the MDX content, and writes a report to the run summary. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/writing/procedures.mdx b/apps/docs/src/content/docs/en/pages/style-guide/writing/procedures.mdx index 26d728a4dc..cc4e73d234 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/writing/procedures.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/writing/procedures.mdx @@ -120,7 +120,7 @@ Every command the reader runs is followed by the output they should see. Show th Input and output take different blocks: a `` block for the command the reader copies, a fence for the output they read. The mechanics are in [Components](/en/documentation/style-guide/components/). -When a command produces no output, state the resulting state instead. When you can state neither, cut the command or restructure the step around a result the reader can check: a command the reader cannot verify is worse than one less command. Never write output you have not seen the command produce. +When a command produces no output, state the resulting state instead. When you can state neither, cut the command or restructure the step around a result the reader can check. A command the reader cannot verify is worse than one less command. Never write output you have not seen the command produce. ## Multiple interfaces diff --git a/apps/docs/src/content/docs/en/pages/style-guide/writing/sentence-structure.mdx b/apps/docs/src/content/docs/en/pages/style-guide/writing/sentence-structure.mdx index 90c5c21e0d..6c3c8ade41 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/writing/sentence-structure.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/writing/sentence-structure.mdx @@ -10,20 +10,24 @@ permalink: /documentation/style-guide/writing/sentence-structure/ ## Write for a reader who cannot ask -The aerospace and defense industry publishes ASD-STE100, a controlled language for technical writing. Issue 9, dated 15 January 2025, contains 53 writing rules in nine sections. The standard also carries a dictionary of about 900 approved words. Each word in that dictionary has one meaning and one part of speech. +The aerospace and defense industry publishes ASD-STE100, a controlled language for technical writing. Issue 9 contains 53 writing rules in nine sections. The standard also carries a dictionary of about 900 approved words. Each word in that dictionary has one meaning and one part of speech. Azion documentation follows the sentence rules of this standard because its readers match the standard's target reader. Many readers work in a second language. No author is present to answer a question. Retrieval systems index these pages in sections and return one section, not the whole page. A sentence that follows these rules also translates to Brazilian Portuguese with less drift. ## Match the sentence cap to the content type -ASD-STE100 sets stricter rules for procedures than for descriptions. Azion maps that split onto the four base forms. +ASD-STE100 sets stricter rules for procedures than for descriptions. Azion maps that split onto every page kind in [Choose a content type](/en/documentation/style-guide/content/choose-a-content-type/). -| Content type | Mode | Sentence cap | -| --- | --- | --- | -| Tutorial | Procedural | 20 words | -| How-to | Procedural | 20 words | -| Reference | Descriptive | 25 words | -| Explanation | Descriptive | 25 words | +| Base form | Page kinds | Mode | Sentence cap | +| --- | --- | --- | --- | +| Tutorial | Quickstart, tutorial | Procedural | 20 words | +| How-to | How-to guide, multi-resource guide, troubleshooting | Procedural | 20 words | +| Reference | Overview, reference, glossary | Descriptive | 25 words | +| Explanation | Concept, architecture, use case | Descriptive | 25 words | +| Record | Changelog | Descriptive | 25 words | +| None | Navigation hub | Descriptive | 25 words | + +A use case takes the explanation form. Its prose describes a design and why it takes that shape, and every step lives in the guides it links. A procedure gets the tighter cap because the reader executes each step under load. A step that the reader misreads becomes an action that fails. The caps count prose sentences only. Table cells, code, and command output are exempt. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/writing/terminology.mdx b/apps/docs/src/content/docs/en/pages/style-guide/writing/terminology.mdx index 077e55e7cf..1500441282 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/writing/terminology.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/writing/terminology.mdx @@ -46,7 +46,7 @@ Azion renamed its offerings over time. The old names still appear in old pages, ## Name the resource the reader works on -Azion describes what it offers with four terms. They are related concepts, not four levels of one hierarchy: a Platform Resource may or may not be a Product, and a Feature can belong to the Platform or to a Platform Resource. +Azion describes what it offers with four terms. They are related concepts, not four levels of one hierarchy. A Platform Resource may or may not be a Product, and a Feature can belong to the Platform or to a Platform Resource. | Term | Answers | Definition | | --- | --- | --- | @@ -55,7 +55,7 @@ Azion describes what it offers with four terms. They are related concepts, not f | Platform Resource | What does the reader create or manage? | An identifiable entity that the customer creates, configures, operates, or manages, and that Console, the API, the CLI, or the documentation can reference, such as an Application, a Firewall, a Function, or a bucket | | Feature | What can the reader do or turn on? | A user-visible functionality of the Platform or of a Platform Resource, which a Product can include, such as custom firewall rules or DNSSEC | -Documentation uses the Platform Resource nomenclature. Product is a go-to-market term, used mainly in marketing and sales material, and the table defines it so the reader recognizes it there. A documentation page calls each section by its official name and calls the offering a Platform Resource, never a product: it names what the reader creates or manages, and it joins one Platform Resource to another with a verb. Product never classifies an element on a page, per [State the class of an Azion element](#state-the-class-of-an-azion-element). +Documentation uses the Platform Resource nomenclature. Product is a go-to-market term, used mainly in marketing and sales material, and the table defines it so the reader recognizes it there. A documentation page calls each section by its official name and calls the offering a Platform Resource, never a product. The page names what the reader creates or manages, and it joins one Platform Resource to another with a verb. Product never classifies an element on a page, per [State the class of an Azion element](#state-the-class-of-an-azion-element). A Feature is always scoped, so state whether it applies to the Platform or to a Platform Resource. A field or an option on a Platform Resource is a setting, not a Feature. @@ -80,7 +80,7 @@ The class follows the documentation's nomenclature, not the naming catalog's lis Product is a go-to-market term that names an offering, not a class: a page never states it as the class of an element. -- **Once per page, at the element's first definition.** That is the first sentence of an Overview, each entry of its resources section, the sentence of a concept page that introduces the element, a glossary row that defines it, and the first sentence of any other page that says what the element is. +- **Once per page, at the element's first definition.** That is the first sentence of an Overview and each entry of its resources section. It is also the sentence of a concept page that introduces the element, and a glossary row that defines it. On any other page that says what the element is, it is the first sentence. - **A mention in passing carries no class.** `Create a Firewall` and `Open the Application` stay as they are. A changelog entry describes a change, not the element, and keeps the opening that [Changelog pages](/en/documentation/style-guide/content/changelog/) sets. - **The class does not replace the concept.** The class says what the element is within Azion. The concept sentences after it still say what the class of thing is with any vendor: a reverse proxy is a server in front of your origins. - **Brazilian Portuguese** writes the classes as `recurso da plataforma` and `feature`: `**Functions** é um recurso da plataforma que executa código JavaScript na infraestrutura distribuída da Azion.` @@ -117,7 +117,7 @@ The thing a customer creates with a Platform Resource takes that resource's name | Connectors | a Connector | Connectors | um Connector | | Workloads | a Workload | Workloads | um Workload | -An Azion element with a name of its own that Console or the naming catalog lists as a resource follows the same rule: a Function Instance, the instance of a Function on an Application or a Firewall, and a Network List. +An Azion element with a name of its own follows the same rule when Console or the naming catalog lists it as a resource. These elements are a Function Instance, the instance of a Function on an Application or a Firewall, and a Network List. Three things stay common nouns, in lowercase: @@ -127,7 +127,7 @@ Three things stay common nouns, in lowercase: The reader tells the Platform Resource from its instances by the grammar. The Platform Resource takes no article and a singular verb: `Applications routes…`, `Applications encaminha…`. An instance takes an article, a possessive, or a number: `an Application`, `your Applications`, `uma Application`, `duas Applications`. -The name already ties the instance to its Platform Resource, so no sentence has to. When a sentence must say what an instance is, its class noun is `entity`, `entidade` in Brazilian Portuguese, never `object` or `objeto`: `A Workload is the entity that holds your domains…`. A lowercase or translated instance reads as the customer's own app or as a generic function, and a reader who knows the product reads the translation as a different name for it. +The name already ties the instance to its Platform Resource, so no sentence has to. When a sentence must say what an instance is, its class noun is `entity`, `entidade` in Brazilian Portuguese, never `object` or `objeto`: `A Workload is the entity that holds your domains…`. A lowercase or translated instance reads as the customer's own app or as a generic function. A reader who knows the product reads the translation as a different name for it. - Correct: `Deploy your first Application.` - Correct: `An Application receives the requests of a Workload once that Workload's deployment sets that Application.` @@ -136,7 +136,7 @@ The name already ties the instance to its Platform Resource, so no sentence has ## Keep historical names in historical documents -Changelogs, release notes, and dated agreements record what was true on the day of publication. These documents keep the names they shipped with. A Terms of Service from 2020 keeps the names that were correct in 2020. +Changelogs, release notes, and dated agreements record what was true on the day of publication. These documents keep the names they shipped with. A Terms of Service keeps the names that were correct on the day it was published. Do not rename an offering in a historical document. An updated name rewrites the record and detaches the text from its date. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/writing/word-choice.mdx b/apps/docs/src/content/docs/en/pages/style-guide/writing/word-choice.mdx index e4e07a0a87..a048bfbb1c 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/writing/word-choice.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/writing/word-choice.mdx @@ -53,7 +53,7 @@ Two sentences in a row that open with the same words, or that share the same gra - Before: `A data center that holds a valid copy answers from cache. A data center that holds no valid copy fetches the object from the origin.` - After: `When a data center holds a valid copy, it answers from cache. Otherwise the data center fetches the object from the origin.` -Three techniques break the pattern: lead with the condition rather than the subject; contrast with a connective such as `Otherwise` instead of naming the subject twice; and let one sentence carry two clauses when they are one thought. A paragraph whose sentences all run the same mid-length reads the same way, so vary the length and prefer short. +Three techniques break the pattern. Lead with the condition rather than the subject. Contrast with a connective such as `Otherwise` instead of naming the subject twice. Let one sentence carry two clauses when they are one thought. A paragraph whose sentences all run the same mid-length reads the same way, so vary the length and prefer short. ## Name things in headings @@ -70,7 +70,7 @@ Do not call a task "simple", "easy", "straightforward", or "obvious", and do not Do not write "please". Documentation instructs. It does not ask. -Do not anchor a page in time with "currently", "at the time of writing", "will soon", "now available", "recently", or "new" as a modifier. All of them age badly, and nobody returns to fix them. No month or year appears outside a changelog: say what is true and let the changelog carry the timeline. A date a build step generates, such as the last-updated column on a Guides and tutorials hub, is exempt, because nothing written by hand goes stale there. +Do not anchor a page in time with "currently", "at the time of writing", "will soon", "now available", "recently", or "new" as a modifier. All of them age badly, and nobody returns to fix them. No month or year appears in hand-written prose outside a changelog: say what is true and let the changelog carry the timeline. [Numbers and units](/en/documentation/style-guide/formatting/numbers/#format-a-date-only-where-a-date-belongs) lists the few other places a date belongs, such as the dates a build step generates. Write "for example" and "that is", never "e.g." and "i.e.". diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/como-documentamos/docs-as-code.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/como-documentamos/docs-as-code.mdx index 1f28bdc062..5eb0803cb0 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/como-documentamos/docs-as-code.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/como-documentamos/docs-as-code.mdx @@ -34,7 +34,7 @@ O **CI gate** agrupa quatro jobs. Um primeiro job lê o diff e roda só os jobs | Code quality | ESLint, Prettier e Stylelint nos arquivos que o pull request altera, e `astro check` | Um erro de lint ou de formatação em um arquivo alterado, e mais erros de tipo que a baseline | | Build | `astro build`, depois `test:frontmatter` | Uma página que não compila, e um `permalink` ausente, malformado ou duplicado, ou um `namespace` duplicado | -O **Internal links** faz o build do site e roda o verificador de links. O verificador segue só links internos. Ele aponta um link para uma página ou um fragmento que não existe, um link para uma página de redirect em vez da URL canônica, uma URL absoluta onde cabe uma relativa e um link para uma página no outro idioma. A verificação de texto vago cobre todo link, interno ou externo: ela aponta textos de link como "here" ou "read more". +O **Internal links** faz o build do site e roda o verificador de links. O verificador segue só links internos. Ele aponta um link para uma página ou um fragmento que não existe, e um link para uma página de redirect em vez da URL canônica. Ele também aponta uma URL absoluta onde cabe uma relativa e um link para uma página no outro idioma. A verificação de texto vago cobre todo link, interno ou externo: ela aponta textos de link como "here" ou "read more". O **Design system adoption** roda as regras de lint do design system sobre a UI e o conteúdo MDX, e escreve um relatório no resumo da execução. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx index 958f8ac07c..69673fc267 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx @@ -106,12 +106,12 @@ import Code from '~/components/webkit/CodeBlock.vue' ``` - `client:visible` é obrigatório. Sem ele, as tabs renderizam e não alternam. -- Um bloco pareia cada `tab.x` com um `panel.x`. A única exceção é uma página que documenta mais de uma interface, como uma [página de Quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) ou um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/): o bloco de pré-requisitos declara a faixa de tabs, e todo bloco seguinte da mesma `sharedStore` tem apenas slots `panel.x`. Um bloco só de painéis da store `interface` renderiza essa faixa acima dos próprios painéis, então o leitor troca de interface em qualquer seção. +- Um bloco pareia cada `tab.x` com um `panel.x`. A única exceção é uma página que documenta mais de uma interface, como uma [página de Quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) ou um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/). Nessa página, o bloco de pré-requisitos declara a faixa de tabs, e todo bloco seguinte da mesma `sharedStore` tem apenas slots `panel.x`. Um bloco só de painéis da store `interface` renderiza essa faixa acima dos próprios painéis, então o leitor troca de interface em qualquer seção. - **Linhas em branco ao redor de markdown dentro de um Fragment são obrigatórias**, ou o markdown renderiza como um único parágrafo literal. - Os painéis são pareados com as tabs pela chave, e a primeira tab é o padrão. Um bloco `interface` renderiza as tabs em uma única ordem em todas as páginas, qualquer que seja a ordem declarada no MDX: Console, GraphiQL, CLI, GitHub, API. Escreva nessa ordem mesmo assim, para que a página e a sua versão em Markdown sejam lidas da mesma forma. - Chaves canônicas: `tab.console`, `tab.api`, `tab.cli`, mais `tab.apiv3` / `tab.apiv4` para APIs versionadas. Uma chave tem apenas letras minúsculas e dígitos: um hífen escapa da checagem de pareamento `tab.x` / `panel.x` sem falhar nela. - Em um bloco com `sharedStore="interface"`, abra cada painel com um título um nível abaixo da seção em que ele está, com o rótulo da tab: `### Console`. Esses títulos ficam fora do sumário, e cada um aponta para a sua seção com a sua interface selecionada: `?interface=console#crie-um-banco-de-dados`. -- O `sharedStore=""` opcional sincroniza a seleção entre grupos de tabs de uma página. Tabs de interface usam `sharedStore="interface"`, então uma seleção acompanha o leitor em uma página que repete as tabs por seção, e também até a página seguinte: essa única store é guardada no navegador e escrita na URL como `?interface=`, o que deixa o fragmento livre para uma seção. Dê a todo bloco que compartilha uma chave as mesmas tabs. Um bloco que não oferece a chave selecionada abre no próprio primeiro painel, e deixa a seleção intacta para os blocos que a oferecem. +- O `sharedStore=""` opcional sincroniza a seleção entre grupos de tabs de uma página. Tabs de interface usam `sharedStore="interface"`, então uma seleção acompanha o leitor em uma página que repete as tabs por seção, e também até a página seguinte. Essa única store é guardada no navegador e escrita na URL como `?interface=`, o que deixa o fragmento livre para uma seção. Dê a todo bloco que compartilha uma chave as mesmas tabs. Um bloco que não oferece a chave selecionada abre no próprio primeiro painel, e deixa a seleção intacta para os blocos que a oferecem. ## Tag @@ -161,9 +161,9 @@ flowchart TD Todo diagrama segue as mesmas regras: -- **Abra com a linha `init` compartilhada** que o exemplo mostra. Ela organiza o diagrama com o ELK, dá espaço aos rótulos e reduz um diagrama mais largo que a coluna até caber nela. Quando o primeiro nó não aparece no topo, adicione um objeto `elk` logo depois de `"layout": "elk",`. Em um diagrama com um ciclo, como uma requisição e a resposta dela, use as opções de ordem do modelo do ELK, para que a ordem de declaração decida as camadas: `"cycleBreakingStrategy": "MODEL_ORDER"`, ou `"preset": "modelOrder", "keepEntryNodeOnTop": true`. Em um diagrama com mais de um nó de partida, use `"layeringStrategy": "LONGEST_PATH_SOURCE"`, que põe todos os nós de partida na primeira linha. +- **Abra com a linha `init` compartilhada** que o exemplo mostra. Ela organiza o diagrama com o ELK, dá espaço aos rótulos e reduz um diagrama mais largo que a coluna até caber nela. Quando o primeiro nó não aparece no topo, adicione um objeto `elk` logo depois de `"layout": "elk",`. Em um diagrama com um ciclo, como uma requisição e a resposta dela, use as opções de ordem do modelo do ELK. Assim a ordem de declaração decide as camadas: `"cycleBreakingStrategy": "MODEL_ORDER"`, ou `"preset": "modelOrder", "keepEntryNodeOnTop": true`. Em um diagrama com mais de um nó de partida, use `"layeringStrategy": "LONGEST_PATH_SOURCE"`, que põe todos os nós de partida na primeira linha. - **Desenhe todo flowchart de cima para baixo** (`flowchart TD`), inclusive uma cadeia de etapas. Uma cadeia desenhada da esquerda para a direita fica mais larga que a coluna e reduz os rótulos para caber. -- **Dê uma forma a cada papel.** O cliente é um estádio (`(["Cliente"])`), tudo o que está na Azion, um produto ou um recurso da plataforma, é um retângulo (`["aplicação"]`), um armazenamento de dados é um cilindro (`[("KV Store")]`), e um sistema fora da Azion é uma sub-rotina (`[["servidor de origem"]]`). Uma etapa, um estado ou uma decisão mantém o retângulo ou o losango. +- **Dê uma forma a cada papel.** O cliente é um estádio (`(["Cliente"])`). Tudo o que está na Azion, um produto ou um recurso da plataforma, é um retângulo (`["aplicação"]`). Um armazenamento de dados é um cilindro (`[("KV Store")]`), e um sistema fora da Azion é uma sub-rotina (`[["servidor de origem"]]`). Uma etapa, um estado ou uma decisão mantém o retângulo ou o losango. - **Deixe o estilo da linha dizer para onde o fluxo vai.** Quando um diagrama desenha uma requisição e a resposta dela, setas contínuas (`-->`) levam a requisição e setas pontilhadas (`-.->`) levam a resposta. Um fluxo que roda separado de qualquer requisição, como um purge ou um stream de logs, usa setas grossas (`==>`). ## Passos @@ -252,12 +252,12 @@ import DocItem from '@aziontech/webkit/doc-item' ## Entrada de changelog -Uma entrada datada: rótulo e versão à esquerda, as notas à direita, com uma âncora derivada do rótulo. +Uma entrada datada: rótulo e versão à esquerda, as notas à direita e uma âncora no rótulo. ```mdx import DocUpdate from '@aziontech/webkit/doc-update' - + **Bot Manager** agora traz nove novas regras estáticas e dois novos argumentos. @@ -265,9 +265,9 @@ import DocUpdate from '@aziontech/webkit/doc-update' ``` - Sem diretiva client. Linhas em branco ao redor do markdown interno são obrigatórias. -- `label` é a âncora, em slug. Duas entradas com o mesmo rótulo precisam de valores distintos de `anchor`. +- Sempre passe `anchor`. O painel da direita lista apenas as entradas que trazem um, e sem ele o id cai no `label` em slug. Duas entradas com o mesmo rótulo precisam de valores distintos de `anchor`. - `description` é a linha abaixo do rótulo; `tags` é um array de rótulos curtos. -- Uma página de entradas tem o sumário montado a partir delas: o painel da direita lista uma linha por data e aponta para a primeira entrada daquela data, no lugar dos títulos dentro das notas. O padrão de [Changelog](/pt-br/documentacao/guia-de-estilo/conteudo/changelog/) tem o resto. +- Uma página de entradas tem o sumário montado a partir delas. O painel da direita lista uma linha por data e aponta para a primeira entrada daquela data, no lugar dos títulos dentro das notas. O padrão de [Changelog](/pt-br/documentacao/guia-de-estilo/conteudo/changelog/) tem o resto. ## Prompt @@ -325,7 +325,7 @@ Uma página sobre um recurso que existe na API v3 e na API v4 tem exatamente um | `versionDualSteps` | O fim da introdução de um guia com passos para a API v4 e para a API v3 | Nenhuma | A API v4 chega a todas as contas. Os passos da API v3 saem junto | | `versionDeprecated` | O topo de uma página da API v3 | Um link para a página da API v4, com o título dela | A API v4 chega a todas as contas. A página passa a redirecionar para a contraparte na API v4, nunca para uma página inicial | -Uma página da API v3 não aparece na navegação. A linha dela na árvore de navegação tem `"hidden": true`, então a página mantém a sidebar e o breadcrumb do recurso da plataforma, e o leitor chega a ela pelo aviso da contraparte na API v4. +Uma página da API v3 não aparece na navegação. A linha dela na árvore de navegação tem `"hidden": true`, então a página mantém a sidebar e o breadcrumb do recurso da plataforma. O leitor chega a ela pelo aviso da contraparte na API v4. A data em que a API v3 for desligada aparece só em `versionDeprecated` e em [Migração para API v4](/pt-br/documentacao/fundamentos/api-v4-migration/). @@ -345,6 +345,7 @@ import ProductGuidesSection from '~/components/ProductGuidesSection.astro' - `product` — o id da seção, como `applications`. A tabela lista todo guia que o catálogo de guias marca com a seção ou com um recurso da plataforma aninhado nela. - A data é a da última alteração da página, preenchida automaticamente. Nunca escreva a data à mão. +- A tabela também lista os vídeos que a lista de vídeos da navegação marca com a seção. Uma linha de vídeo abre o YouTube em uma nova aba, o tipo ganha Vídeo e a data fica vazia. - A coluna de tipo mostra o tipo de conteúdo de cada página, no idioma do leitor. - As linhas ordenam em ordem alfabética pelo rótulo de navegação de cada página, no idioma do leitor, nunca por data. A coluna de nome mostra esse rótulo, não o título da página. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx index c478816a00..9febe637dc 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx @@ -16,7 +16,7 @@ Dois princípios organizam tudo. As seções seguem a ordem da jornada do leitor Toda seção de recurso da plataforma segue esta ordem. A tabela mostra o que cada slot contém e quando ele existe. -Um tipo de recurso da plataforma com seção própria (Workloads, Edge DNS, Applications, Connectors, Firewall) segue o mesmo esqueleto. A visão geral descreve o tipo de recurso, o quickstart cria a primeira instância, e Glossário, Preços e Changelog são obrigatórios, como em toda seção. Um recurso da plataforma aninhado em outro não mantém seção própria: ele entra na seção do recurso pai como uma linha dropdown na posição do slot 4, e a URL dele fica aninhada sob o pai, como em `/documentacao/plataforma/firewall/waf/`. A regra de aninhamento e o que o dropdown contém estão em [Recursos da plataforma aninhados](#recursos-da-plataforma-aninhados). +Um tipo de recurso da plataforma com seção própria (Workloads, Edge DNS, Applications, Connectors, Firewall) segue o mesmo esqueleto. A visão geral descreve o tipo de recurso, o quickstart cria a primeira instância, e Glossário, Preços e Changelog são obrigatórios, como em toda seção. Um recurso da plataforma aninhado em outro não mantém seção própria. Ele entra na seção do recurso pai como uma linha dropdown na posição do slot 4, e a URL dele fica aninhada sob o pai, como em `/documentacao/plataforma/firewall/waf/`. A regra de aninhamento e o que o dropdown contém estão em [Recursos da plataforma aninhados](#recursos-da-plataforma-aninhados). | Ordem | Slot | Obrigatório | Contém | | --- | --- | --- | --- | @@ -38,7 +38,7 @@ Dois slots têm uma forma fixa na sidebar. **Guias e tutoriais é uma linha que abre uma página.** A linha aponta para um hub cujo corpo é uma única tabela: nome, tipo e última atualização, uma linha por guia e por tutorial. A sidebar nunca expande essa linha, e o leitor abre um guia a partir da tabela. Uma seção com quarenta guias continua sendo uma linha na sidebar, então a sidebar segue mostrando a seção inteira. -A tabela é gerada, não escrita. A data é a da última alteração da página e o tipo é o tipo de conteúdo que o catálogo de guias registra para a página, então o hub não diverge das páginas que lista. +A tabela é gerada, não escrita. A data é a da última alteração da página, e o tipo é o tipo de conteúdo que o catálogo de guias registra para a página. Por isso o hub não diverge das páginas que lista. **Referência é um grupo fixo.** A sidebar mostra um pai **Referência** com uma linha por página de referência. O nome do grupo é o mesmo em toda seção de recurso da plataforma, então o leitor encontra os campos no mesmo lugar em todas. @@ -52,11 +52,23 @@ Uma feature com superfície própria repete o padrão um nível abaixo: Tiered C ## Recursos da plataforma aninhados -Um recurso da plataforma aninhado em outro é uma linha dropdown dentro da seção do recurso pai, na posição do slot 4, sem rótulo de grupo: WAF, Network Shield e Bot Manager dentro de Firewall; Cache, Application Accelerator e Image Processor dentro de Applications; Load Balancer, Origin Shield e Live Ingest dentro de Connectors; Certificate Manager, Custom Pages e DDoS Protection dentro de Workloads. Em uma página, a classe dele é recurso da plataforma, qualquer que seja a classe no catálogo de nomes. Ele mantém só as páginas que são dele: as páginas de referência, um Quickstart quando tem uma configuração inicial própria e, opcionalmente, uma visão geral própria, para a qual a visão geral do pai aponta. Sem uma visão geral, o dropdown dele ganha um hub de grupo, então o item dele no breadcrumb continua abrindo uma página. Quando ele tem um mecanismo a explicar, o grupo Referência dele abre com uma página de mecanismo: uma [página de conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/) com o título do mecanismo, como Score e modos para o WAF. Todo o resto que o leitor precisa saber sobre ele é escrito uma vez, nas páginas do pai: o que ele faz e quando ativá-lo na visão geral do pai, uma seção `## ` na página Como funciona do pai que o apresenta e aponta para a página de mecanismo dele, os limites, as práticas e os sintomas nas páginas Limites, Boas práticas e Troubleshooting do pai, os termos no glossário do pai e os guias no hub do pai. +Um recurso da plataforma aninhado em outro é uma linha dropdown dentro da seção do recurso pai, na posição do slot 4, sem rótulo de grupo. Quatro recursos pai têm recursos da plataforma aninhados: -Um recurso da plataforma se aninha quando a configuração dele vive nas configurações ou nas regras do próprio recurso pai: uma flag em `modules`, um behavior do Rules Engine ou um campo do pai. Um recurso da plataforma que o leitor consome do código (Functions, Object Storage, SQL Database, KV Store, AI Inference) e um serviço autônomo (Edge DNS, Data Stream, Orchestrator) ficam na raiz de Recursos de Plataforma. Uma feature é uma página dentro do recurso da plataforma dela, nunca um dropdown. +- Firewall: WAF, Network Shield e Bot Manager. +- Applications: Cache, Application Accelerator e Image Processor. +- Connectors: Load Balancer, Origin Shield e Live Ingest. +- Workloads: Certificate Manager, Custom Pages e DDoS Protection. -O Quickstart carrega a interface dentro da página. Um recurso da plataforma cujo primeiro uso passa por Azion Console, pela Azion CLI ou pela API mantém uma página e seleciona a interface com tabs, então o slot tem uma linha e uma URL. O slot se divide apenas quando as interfaces não podem compartilhar um esqueleto de etapas, e para um agente de IA, cujo caminho é conduzido por prompt e não compartilha etapa com os outros. Essas páginas ficam agrupadas sob Quickstart, com o Console primeiro; o grupo é um pai da sidebar com um hub de grupo, não uma visão geral. [Páginas de quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) tem o teste. +Em uma página, a classe de um recurso da plataforma aninhado é recurso da plataforma, qualquer que seja a classe no catálogo de nomes. Ele mantém só as páginas que são dele. São as páginas de referência, um Quickstart quando tem uma configuração inicial própria e uma visão geral opcional, para a qual a visão geral do pai aponta. Sem uma visão geral, o dropdown dele ganha um hub de grupo, então o item dele no breadcrumb continua abrindo uma página. Quando ele tem um mecanismo a explicar, o grupo Referência dele abre com uma página de mecanismo. Essa é uma [página de conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/) com o título do mecanismo, como Score e modos para o WAF. Todo o resto que o leitor precisa saber sobre ele é escrito uma vez, nas páginas do pai: + +- A visão geral do pai diz o que ele faz e quando ativá-lo. +- A página Como funciona do pai tem uma seção `## ` que o apresenta e aponta para a página de mecanismo dele. +- As páginas Limites, Boas práticas e Troubleshooting do pai trazem os limites, as práticas e os sintomas dele. +- O glossário do pai traz os termos dele, e o hub do pai lista os guias dele. + +Um recurso da plataforma se aninha quando a configuração dele vive nas configurações ou nas regras do próprio recurso pai. Essa configuração é uma flag em `modules`, um behavior do Rules Engine ou um campo do pai. Um recurso da plataforma que o leitor consome do código (Functions, Object Storage, SQL Database, KV Store, AI Inference) fica na raiz de Recursos de Plataforma. Um serviço autônomo (Edge DNS, Data Stream, Orchestrator) também fica ali. Uma feature é uma página dentro do recurso da plataforma dela, nunca um dropdown. + +O Quickstart carrega a interface dentro da página. Um recurso da plataforma cujo primeiro uso passa por Azion Console, pela Azion CLI ou pela API mantém uma página e seleciona a interface com tabs. O slot então tem uma linha e uma URL. O slot se divide apenas quando as interfaces não podem compartilhar um esqueleto de etapas. Ele também se divide para um agente de IA, cujo caminho é conduzido por prompt e não compartilha etapa com os outros. Essas páginas ficam agrupadas sob Quickstart, com o Console primeiro; o grupo é um pai da sidebar com um hub de grupo, não uma visão geral. [Páginas de quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) tem o teste. O onboarding da plataforma, como [Criar uma conta](/pt-br/documentacao/fundamentos/criar-uma-conta/) em Fundamentos, é outra coisa. Primeiros passos é o slot de um recurso da plataforma. O onboarding é a porta de entrada da plataforma, e não pertence a nenhum recurso da plataforma. @@ -64,7 +76,7 @@ O onboarding da plataforma, como [Criar uma conta](/pt-br/documentacao/fundament - **A ordem espelha a adoção.** Um slot nunca fica à frente da sua etapa. - **Preços e Changelog fecham a seção.** O leitor os consulta em vez de passar por eles. -- **A coluna Obrigatório decide o que é publicado.** Todo outro slot existe somente quando conteúdo real o preenche. A coluna vale para uma seção; um recurso da plataforma aninhado precisa somente das páginas de referência, de uma página de mecanismo quando tem um mecanismo a explicar e de um Quickstart quando tem uma configuração inicial própria. +- **A coluna Obrigatório decide o que é publicado.** Todo outro slot existe somente quando conteúdo real o preenche. A coluna vale para uma seção. Um recurso da plataforma aninhado sempre precisa das páginas de referência. Ele também precisa de uma página de mecanismo quando tem um mecanismo a explicar, e de um Quickstart quando tem uma configuração inicial própria. - **Nunca adicione um slot para completar o padrão**, e nunca mantenha um vazio como marcador. - **A lista de slots é fechada. Cresça dividindo um slot que a seção já tem:** Guias e tutoriais em grupos de tarefa nomeados na página de hub, Features por superfície. O slot Primeiros passos cresce dentro da própria página, por tabs de interface, e se divide apenas quando as etapas não podem ser compartilhadas. Uma lista fixa é o que permite ao leitor achar o mesmo slot no mesmo lugar em toda seção. @@ -89,7 +101,7 @@ Conteúdo que nenhum recurso da plataforma possui sozinho vive ao lado das seç - A página documenta um recurso da plataforma: entra na seção desse recurso, no slot que o tipo de conteúdo indica. - A página explica a plataforma, contas ou billing: entra em Fundamentos. - A página diagnostica problemas de plataforma ou leva ao time de suporte: entra em Suporte. -- A página constrói um caso de uso do catálogo: é um [caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/), e entra em Casos de uso, na área da solução da sua entrada. +- A página explica um caso de uso do catálogo: é um [caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/), e entra em Casos de uso, na área da solução da sua entrada. - A página mostra uma arquitetura de referência do catálogo, como produtos e recursos da plataforma se combinam em um design: entra em Architectures, sob a sua solução. - A página reúne links de uma área: é um [hub de navegação](/pt-br/documentacao/guia-de-estilo/conteudo/hubs-de-navegacao/), e precisa de um público real antes de existir. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx index b44dbfdae3..591dbfe1f9 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx @@ -28,7 +28,7 @@ Escreva uma página de arquitetura quando: Não escreva uma página de arquitetura quando: - O assunto é um recurso da plataforma ou uma ideia. Escreva uma [página de conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/). -- O leitor quer construir a coisa. Escreva a [página de caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/) que a constrói, ou um [guia multirrecurso](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multirrecurso/), e aponte para ela daqui. +- O leitor quer construir a coisa. Escreva a [página de caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/) que a explica e aponta os guias que a constroem, ou um [guia multirrecurso](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multirrecurso/), e aponte para ela daqui. - O catálogo não tem entrada para o design. Proponha o design ao catálogo de casos de uso primeiro; a página vem depois da entrada. - O design não pode ser desenhado. Um design que você não consegue desenhar é um design que você ainda não entende bem o suficiente para publicar. @@ -44,7 +44,7 @@ O título é o nome da arquitetura de referência no catálogo, sem alteração, - **`## Diagrama de arquitetura`**: uma legenda de uma ou duas frases, depois o diagrama como um bloco de código `mermaid`, com o `### Fluxo de dados` logo abaixo dele. - **`### Fluxo de dados`**: um passo a passo numerado do que vai para onde, com no máximo seis itens. Depois da lista, o que o design mostra e nenhuma etapa diz, como qual parte fica no fluxo de falha. -- **`## Componentes`**: um item por componente da entrada do catálogo, com o seu papel. Produtos e recursos da plataforma entram pelo nome, uma instância leva o nome do seu recurso da plataforma (uma Application, uma Function), e features e integrações entram rotuladas como o catálogo as rotula. +- **`## Componentes`**: um item por componente da entrada do catálogo, com o seu papel. Produtos e recursos da plataforma entram pelo nome, e uma instância leva o nome do seu recurso da plataforma (uma Application, uma Function). Features e integrações entram rotuladas como o catálogo as rotula. - **`## Implementação`**: apenas links. A página de caso de uso entra aqui quando ela constrói este design, seguida dos guias e templates do Marketplace que implementam todo o design ou parte dele. Uma página de caso de uso que constrói um design irmão recebe o link no parágrafo de abertura, como o caso de uso que a arquitetura implementa, e não aqui. - **`## Recursos relacionados`**: a seção de fechamento, uma lista de `DocItem`, cada linha com sua razão. @@ -102,7 +102,7 @@ flowchart TD - **Siga as regras de diagrama de [Componentes](/pt-br/documentacao/guia-de-estilo/componentes/#diagramas-mermaid)**: a linha `init` compartilhada, de cima para baixo, e uma forma por papel. - **Desenhe a requisição e o caminho de volta.** Setas contínuas (`-->`) levam a requisição, e setas pontilhadas (`-.->`) levam a resposta. Um fluxo que roda separado de qualquer requisição, como uma publicação, um purge ou um stream de logs, usa setas grossas (`==>`). Uma seta de resposta começa onde a resposta começa: o Cache em um hit, o firewall em um bloqueio, a origem em um miss. Ela passa por um componente só quando esse componente age sobre a resposta, como o Cache que armazena uma cópia. Uma resposta que a aplicação trata volta pela aplicação, que a entrega. Uma resposta que o firewall dá vai direto ao cliente, porque a aplicação nunca recebe essa requisição. Uma leitura também tem caminho de volta: uma seta pontilhada do armazenamento de dados até o componente que leu, com o rótulo do que ele devolve. A legenda acima do diagrama diz o que cada estilo de seta leva. - **Numere cada seta pela etapa do fluxo de dados.** Cada rótulo de seta começa pelo número do item do `### Fluxo de dados` a que pertence, como `2, 4. miss`. Todo item tem pelo menos uma seta, e toda seta tem um item. O caminho de volta pertence à etapa que ele responde, então nunca acrescenta uma etapa. -- **Ponha o fluxo de dados logo abaixo do diagrama.** A legenda fica acima do diagrama, e o `### Fluxo de dados` vem logo depois do bloco, sem nada entre os dois, para que as setas e as etapas que elas numeram fiquem na tela ao mesmo tempo. Uma frase que só reconta uma etapa não acrescenta nada e sai. +- **Ponha o fluxo de dados logo abaixo do diagrama.** A legenda fica acima do diagrama, e o `### Fluxo de dados` vem logo depois do bloco, sem nada entre os dois. Assim as setas e as etapas que elas numeram ficam na tela ao mesmo tempo. Uma frase que só reconta uma etapa não acrescenta nada e sai. - **Nomeie cada componente e diga por que ele está ali.** Uma lista de nomes de recurso da plataforma é uma lista de peças. - **Aponte para a implementação, não a coloque aqui.** Os passos vão em um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) ou em um [guia multirrecurso](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multirrecurso/). - **Escreva só as seções que você consegue confirmar.** Uma seção obrigatória cujo conteúdo você não consegue confirmar com o time que cuida do recurso da plataforma fica de fora até que consiga, nunca é preenchida com um palpite. @@ -153,7 +153,7 @@ O conteúdo percorre o design nesta ordem: O fluxo de publicação só se move em um push, e os dois fluxos só se encontram no bucket. ```` -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/casos-de-uso.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/casos-de-uso.mdx index d7cc2a6c43..0b9a8e31fe 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/casos-de-uso.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/casos-de-uso.mdx @@ -14,9 +14,9 @@ import DocItem from '@aziontech/webkit/doc-item' ## Propósito -Uma página de caso de uso explica uma entrada do catálogo de casos de uso como um design: o que o cenário precisa, quais recursos o atendem e por que o design tem a forma que tem. A entrada dá à página o título, o cenário, os produtos e as arquiteturas de referência que ela pode construir. A página nunca inventa um caso de uso próprio. O catálogo é mantido pela Azion. Quem precisa de uma entrada, ou encontra uma errada, pede antes de escrever a página. O pedido vai pelos templates de issue do repositório, ou pelo dono do catálogo dentro da Azion. O leitor chega com uma situação, não com uma tarefa: uma loja que fica lenta durante uma promoção, um evento ao vivo que precisa alcançar mais uma região. +Uma página de caso de uso explica uma entrada do catálogo de casos de uso como um design. Ela diz o que o cenário precisa, quais recursos o atendem e por que o design tem a forma que tem. A entrada dá à página o título, o cenário, os produtos e as arquiteturas de referência que ela pode construir. A página nunca inventa um caso de uso próprio. O catálogo é mantido pela Azion. Quem precisa de uma entrada, ou encontra uma errada, pede antes de escrever a página. O pedido vai pelos templates de issue do repositório, ou pelo dono do catálogo dentro da Azion. O leitor chega com uma situação, não com uma tarefa: uma loja que fica lenta durante uma promoção, um evento ao vivo que precisa alcançar mais uma região. -Um caso de uso é teoria, não um procedimento. Ele carrega o que o leitor precisa para entender e decidir: os produtos que o cenário exige, a arquitetura, como cada parte do design funciona e a razão por trás dela, e as métricas que mostram o design funcionando. Os valores de cada configuração, todo procedimento, todo comando e toda verificação ficam nos guias para os quais a página aponta. Cada seção de guia que aplica uma parte do design nomeia o caso de uso e traz os valores que ela usa ali, para que quem implementa, muitas vezes um agente, construa o design a partir desses guias sem fazer uma pergunta. +Um caso de uso é teoria, não um procedimento: ele aplica a forma base de [explicação](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/). Ele carrega o que o leitor precisa para entender e decidir. São os produtos que o cenário exige, a arquitetura, como cada parte do design funciona e por quê, e as métricas que mostram que o design funciona. Os valores de cada configuração, todo procedimento, todo comando e toda verificação ficam nos guias para os quais a página aponta. Cada seção de guia que aplica uma parte do design nomeia o caso de uso e traz os valores que ela usa ali. Quem implementa, muitas vezes um agente, então constrói o design a partir desses guias sem fazer uma pergunta. Casos de uso ficam na seção [Casos de uso](/pt-br/documentacao/casos-de-uso/), nunca dentro da seção de um recurso da plataforma, na área da solução da sua entrada no catálogo. O rótulo da área é o nome da solução. Os guias para os quais um caso de uso aponta ficam na seção Guias. @@ -24,7 +24,7 @@ Casos de uso ficam na seção [Casos de uso](/pt-br/documentacao/casos-de-uso/), **Reconheça um caso de uso por:** -- Um título que é o nome de um caso de uso do catálogo, sem alteração, traduzido na página em português do Brasil: uma frase verbal no infinitivo que nomeia um workload, sem nomes de produto ou de recurso da plataforma, como "Criar vitrines de e-commerce". +- Um título que é o nome de um caso de uso do catálogo, sem alteração, traduzido na página em português do Brasil. O nome é uma frase verbal no infinitivo que nomeia um workload, sem nomes de produto ou de recurso da plataforma, como "Criar vitrines de e-commerce". - Um leitor que chegou com uma situação de negócio, e não com uma tarefa. - Uma tabela de requisitos ligando cada necessidade de negócio ao produto que a atende. - Um resultado que continua mensurável depois que a configuração funciona. @@ -45,7 +45,7 @@ Casos de uso ficam na seção [Casos de uso](/pt-br/documentacao/casos-de-uso/), ## Registro -Descritivo: 20 palavras por frase, voz ativa, presente. Um caso de uso diz o que cada parte do design faz e por quê. O imperativo pertence aos guias para os quais ele aponta. Tom: preciso, claro, objetivo, sóbrio. [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/) tem as regras. +Descritivo: 25 palavras por frase, voz ativa, presente. Um caso de uso diz o que cada parte do design faz e por quê. O imperativo pertence aos guias para os quais ele aponta. Tom: preciso, claro, objetivo, sóbrio. [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/) tem as regras. ## Estrutura @@ -54,11 +54,11 @@ Descritivo: 20 palavras por frase, voz ativa, presente. Um caso de uso diz o que - **Cenário**: três a cinco frases tiradas do Cenário da entrada do catálogo. Elas nomeiam o ator, o workload e a situação em que ele está, o que esta página configura e o resultado mensurável. Seguidas de uma linha declarando o que o caso de uso não cobre, a exclusão da própria entrada. - **Pré-requisitos**: uma seção `## Pré-requisitos`, cada item um link. O primeiro item é a conta Azion, com um link inline para a página de cadastro: `Uma conta Azion. Se você ainda não tem uma, [crie uma conta](https://console.azion.com/signup).` Os outros itens nomeiam o que o leitor já precisa ter, como uma origem, um domínio ou um repositório. Ferramentas, tokens e os valores do exemplo pertencem aos guias. - **Produtos necessários**: a tabela de requisitos. Uma linha por requisito, nomeando a necessidade técnica, o produto que a atende e a página que a documenta. A coluna Produto contém os produtos da entrada do catálogo. Uma dependência que a documentação do recurso da plataforma confirma e a entrada omite também entra na tabela, e a lacuna é informada ao catálogo. A necessidade técnica nomeia o recurso da plataforma que o leitor configura. -- **Arquitetura de referência**: uma seção `## Arquitetura de referência`. Ela abre nomeando qual das arquiteturas de referência da entrada esta página constrói, e depois traz uma legenda de uma ou duas frases, um diagrama em `mermaid` e um `### Fluxo de dados` numerado logo abaixo dele. Depois da lista vêm o que o design mostra e nenhuma etapa diz, uma lista `### Recursos da plataforma` com cada recurso da plataforma e cada Feature e seu papel neste design, e `### Outros designs para este caso de uso`, com um item por outra arquitetura de referência da entrada. -- **Como o design funciona**: uma seção `## Como o design funciona` que abre com uma frase nomeando o que ela explica, e depois um `###` por parte do design específica deste caso de uso, no máximo quatro, cada um com um título nominal, como `### Cache do catálogo`. Cada um explica o que aquela parte faz e por quê: o raciocínio, a lógica da regra e um diagrama quando a lógica se ramifica. Um valor aparece só dentro da frase que dá a razão dele. A seção não tem tabela de valores, passo, verificação nem linha de link para um procedimento. Uma parte atendida pelos padrões de um guia não ganha subseção: a tabela de requisitos aponta o guia que a documenta. +- **Arquitetura de referência**: uma seção `## Arquitetura de referência`. Ela abre nomeando qual das arquiteturas de referência da entrada esta página constrói. Depois traz uma legenda de uma ou duas frases, um diagrama em `mermaid` e um `### Fluxo de dados` numerado logo abaixo dele. Depois da lista vem o que o design mostra e nenhuma etapa diz. Em seguida, uma lista `### Recursos da plataforma` nomeia cada recurso da plataforma e cada Feature com seu papel neste design. Por último, `### Outros designs para este caso de uso` traz um item por outra arquitetura de referência da entrada. +- **Como o design funciona**: uma seção `## Como o design funciona` que abre com uma frase que nomeia o que ela explica. Depois vem um `###` por parte do design específica deste caso de uso, no máximo quatro, cada um com um título nominal, como `### Cache do catálogo`. Cada um explica o que aquela parte faz e por quê: o raciocínio, a lógica da regra e um diagrama quando a lógica se ramifica. Um valor aparece só dentro da frase que dá a razão dele. A seção não tem tabela de valores, passo, verificação nem linha de link para um procedimento. Uma parte atendida pelos padrões de um guia não ganha subseção: a tabela de requisitos aponta o guia que a documenta. - **Medição de resultados**: uma seção `## Medindo resultados` nomeando as métricas que mostram a configuração funcionando, e onde ler cada uma. - **Boas práticas**: uma seção `## Boas práticas` com recomendações sobre o design e o raciocínio por trás de cada uma. -- **Guias deste caso de uso**: um fechamento `## Guias deste caso de uso`, um `DocCardGroup` com um card por guia que traz os valores ou as verificações deste caso de uso: o título, o link e, como texto do card, o que o guia faz por este caso de uso. +- **Guias deste caso de uso**: um fechamento `## Guias deste caso de uso`, um `DocCardGroup` com um card por guia que traz os valores ou as verificações deste caso de uso. Cada card traz o título, o link e, como texto, o que o guia faz por este caso de uso. **Componentes opcionais** @@ -70,7 +70,7 @@ As seções mantêm essa ordem. O que governa a página é a proporção, não o - **Cenário, pré-requisitos, demo e os cards de guia ficam curtos.** Cada um orienta e encaminha. Um cenário que passa de dois parágrafos está vendendo. - **Medição e boas práticas ficam entre os dois.** Cada uma carrega conteúdo real, um sinal a observar ou uma razão, e nenhuma delas é lugar para expandir. -O limite que mantém um caso de uso honesto é o teto de quatro subseções em `## Como o design funciona`, não um comprimento. Uma frase que precisa de uma tabela, de um passo ou de um comando colocou o conteúdo de um guia na página errada: ela vai para a seção do guia que aplica aquela parte, e a razão fica aqui. +O limite que mantém um caso de uso honesto é o teto de quatro subseções em `## Como o design funciona`, não um comprimento. Uma frase que precisa de uma tabela, de um passo ou de um comando colocou o conteúdo de um guia na página errada. Esse conteúdo vai para a seção do guia que aplica aquela parte, e a razão fica aqui. ## Template @@ -176,7 +176,7 @@ flowchart TD ## Regras - **Explique o design e deixe a execução para os guias.** Toda escolha carrega a sua razão, e nada diz "dependendo da sua configuração". O leitor pode ser um agente, e um agente não resolve uma ambiguidade perguntando. -- **Mantenha valores, passos, verificações e código fora da página.** Nenhum bloco de código além do diagrama, nenhuma tabela de configurações, nenhum ``, nenhum ``, nenhuma verificação e nenhum comando. Os valores de uma parte do design vão para a seção do guia que a aplica, abaixo de uma linha que nomeia o caso de uso, e os resultados esperados vão para a seção de confirmação desse guia. Quando nenhum guia tem o procedimento, amplie um guia ou escreva um novo [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) primeiro, e depois aponte para ele. +- **Mantenha valores, passos, verificações e código fora da página.** Nenhum bloco de código além do diagrama, nenhuma tabela de configurações, nenhum ``, nenhum ``, nenhuma verificação e nenhum comando. Os valores de uma parte do design vão para a seção do guia que a aplica, abaixo de uma linha que nomeia o caso de uso. Os resultados esperados vão para a seção de confirmação desse guia. Quando nenhum guia tem o procedimento, amplie um guia ou escreva um novo [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) primeiro, e depois aponte para ele. - **Reduza o cenário a uma configuração construível.** Declare assim: `Um