From 116dddfbfb5fb5654563ca9bfb6e0c8e41fe9d3f Mon Sep 17 00:00:00 2001 From: Bruno Germano Date: Tue, 10 Nov 2026 15:50:02 -0300 Subject: [PATCH 1/8] docs(style-guide): settle closing names, sentence caps, and the date rule --- .../docs/en/pages/style-guide/components.mdx | 7 ++++--- .../style-guide/content/architecture.mdx | 2 +- .../pages/style-guide/content/changelog.mdx | 4 ++-- .../content/choose-a-content-type.mdx | 2 +- .../en/pages/style-guide/content/concept.mdx | 2 +- .../en/pages/style-guide/content/glossary.mdx | 2 +- .../style-guide/content/how-to-guides.mdx | 2 +- .../content/multi-resource-guides.mdx | 2 +- .../style-guide/content/navigation-hubs.mdx | 4 ++-- .../en/pages/style-guide/content/overview.mdx | 2 +- .../pages/style-guide/content/quickstart.mdx | 2 +- .../pages/style-guide/content/reference.mdx | 2 +- .../style-guide/content/troubleshooting.mdx | 2 +- .../pages/style-guide/content/tutorials.mdx | 2 +- .../pages/style-guide/content/use-cases.mdx | 2 +- .../style-guide/conventions/bilingual.mdx | 3 ++- .../pages/style-guide/formatting/numbers.mdx | 7 ++++++- .../writing/sentence-structure.mdx | 21 ++++++++++++------- .../pages/style-guide/writing/word-choice.mdx | 2 +- .../pages/guia-de-estilo/componentes.mdx | 7 ++++--- .../guia-de-estilo/conteudo/arquitetura.mdx | 2 +- .../guia-de-estilo/conteudo/casos-de-uso.mdx | 2 +- .../guia-de-estilo/conteudo/changelog.mdx | 4 ++-- .../guia-de-estilo/conteudo/conceito.mdx | 2 +- .../conteudo/escolher-um-tipo-de-conteudo.mdx | 2 +- .../guia-de-estilo/conteudo/glossario.mdx | 2 +- .../guia-de-estilo/conteudo/guias-how-to.mdx | 2 +- .../conteudo/guias-multirrecurso.mdx | 2 +- .../conteudo/hubs-de-navegacao.mdx | 4 ++-- .../guia-de-estilo/conteudo/quickstart.mdx | 2 +- .../guia-de-estilo/conteudo/referencia.mdx | 2 +- .../conteudo/troubleshooting.mdx | 2 +- .../guia-de-estilo/conteudo/tutoriais.mdx | 2 +- .../guia-de-estilo/conteudo/visao-geral.mdx | 2 +- .../convencoes/paginas-bilingues.mdx | 3 ++- .../escrita/escolha-de-palavras.mdx | 2 +- .../escrita/estrutura-de-frases.mdx | 21 ++++++++++++------- .../guia-de-estilo/formatacao/numeros.mdx | 7 ++++++- 38 files changed, 84 insertions(+), 60 deletions(-) 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 f1a857b1e8..5c3ad62da4 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 @@ -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. @@ -343,6 +343,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..7805c9b6f4 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 @@ -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..ea5426f74b 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 @@ -36,7 +36,7 @@ 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`. - **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. @@ -100,7 +100,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 b2c31c7876..c488664a10 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 @@ -107,7 +107,7 @@ One form per page works because links connect the pages. Each form links out in 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 f5a0476f75..698daadb86 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 @@ -65,7 +65,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..5a2ccf66f0 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 @@ -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/multi-resource-guides.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/multi-resource-guides.mdx index 8fe41125e1..530631420b 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 @@ -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 de03784cba..8d68c1dc6e 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 @@ -91,7 +91,7 @@ import ProductGuidesSection from '~/components/ProductGuidesSection.astro' - **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 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. - **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. -- **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/). @@ -113,7 +113,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..e172067412 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 @@ -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 864714355a..e9855c5e90 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 @@ -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 406b62e8a5..4141bcf5f8 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 @@ -162,7 +162,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..2ffa8eb51d 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 @@ -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..bf9548b673 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 @@ -230,7 +230,7 @@ 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 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 5d5c4dcf7c..7427970531 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 @@ -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/numbers.mdx b/apps/docs/src/content/docs/en/pages/style-guide/formatting/numbers.mdx index c1072962b5..7734423b9d 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 it took effect, 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/writing/sentence-structure.mdx b/apps/docs/src/content/docs/en/pages/style-guide/writing/sentence-structure.mdx index 90c5c21e0d..f01e8ee903 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 @@ -16,14 +16,19 @@ Azion documentation follows the sentence rules of this standard because its read ## 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. - -| Content type | Mode | Sentence cap | -| --- | --- | --- | -| Tutorial | Procedural | 20 words | -| How-to | Procedural | 20 words | -| Reference | Descriptive | 25 words | -| Explanation | Descriptive | 25 words | +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/). + +| 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 | +| How-to | Use case | Descriptive | 20 words | +| Reference | Overview, reference, glossary | Descriptive | 25 words | +| Explanation | Concept, architecture | Descriptive | 25 words | +| Record | Changelog | Descriptive | 25 words | +| None | Navigation hub | Descriptive | 25 words | + +A use case is How-to by base form and descriptive by mode. Its prose describes a design and leaves every step to the guides it links. It keeps the 20-word cap of its base form. 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/word-choice.mdx b/apps/docs/src/content/docs/en/pages/style-guide/writing/word-choice.mdx index e4e07a0a87..e3b094f708 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 @@ -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 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/componentes.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx index 1f076f0234..33cbf764e8 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 @@ -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,7 +265,7 @@ 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. @@ -343,6 +343,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.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx index b44dbfdae3..c0f3cd234a 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 @@ -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..78ee140d7c 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 @@ -231,7 +231,7 @@ No caso de uso [Criar vitrines de e-commerce](/pt-br/documentacao/casos-de-uso/c Application Accelerator não está entre os produtos da entrada do catálogo. A referência do Rules Engine confirma que o behavior **Bypass Cache** exige o Application Accelerator, então a linha o carrega e a lacuna volta para o catálogo. -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/changelog.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/changelog.mdx index 607b416802..01960acb32 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/changelog.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/changelog.mdx @@ -36,7 +36,7 @@ Cada entrada é um `DocUpdate`: a data, a versão e o recurso da plataforma fica **Componentes obrigatórios** -- **Uma entrada `DocUpdate`**, das mais novas para as mais antigas. `label` é a data, ` de de `: datas são permitidas em changelogs e apenas em changelogs. `anchor` é a data como slug, `10-de-julho-de-2026`. +- **Uma entrada `DocUpdate`**, das mais novas para as mais antigas. `label` é a data, ` de de `: um changelog é um dos poucos lugares onde [Números e unidades](/pt-br/documentacao/guia-de-estilo/formatacao/numeros/#formate-uma-data-apenas-onde-uma-data-cabe) permite uma data. `anchor` é a data como slug, `10-de-julho-de-2026`. - **A frase de abertura**: `**** agora .`, com o detalhe concreto: a flag, o campo ou o valor padrão. Quando a mudança é de um recurso da plataforma aninhado em outro, o aninhado é o sujeito. - **O que significa na prática**: o que funciona sem configuração agora, ou o que se comporta de outra forma. - **Quem não é afetado**: configurações existentes, versões anteriores, contas que não aderiram. @@ -100,7 +100,7 @@ Para mais informações, consulte [Azion Bot Manager Lite](/pt-br/documentacao/p ``` -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/conceito.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/conceito.mdx index 6c62e873c9..b1c60af9da 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/conceito.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/conceito.mdx @@ -117,7 +117,7 @@ O comportamento dele depende de cinco mecanismos: as camadas de cache, a região Os usuários finais enviam requisições à infraestrutura distribuída da Azion, onde o conteúdo fica em cache. Sem o Tiered Cache, uma requisição que não encontra o conteúdo na primeira camada de cache vai para a origem. O Tiered Cache adiciona uma segunda camada de cache entre essa primeira camada e os servidores de origem. A camada do Tiered Cache pode responder a uma requisição que não encontrou o conteúdo na primeira camada, e assim a requisição não chega à origem. O conteúdo fica em cache por mais tempo, e a origem recebe menos requisições. ``` -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.mdx index 968013e7f0..192409e7e6 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.mdx @@ -107,7 +107,7 @@ Uma forma por página funciona porque links conectam as páginas. Cada forma apo Duas regras mantêm os links verificáveis: -- **Toda página fecha com links.** A página termina com o fechamento que o tipo dela exige, `## Próximos passos` ou `## Recursos relacionados`, com pelo menos um link para uma página da documentação. Glossário, changelog e hubs de navegação são as exceções, porque cada um já é uma lista de links. +- **Toda página fecha com links.** A página termina com o fechamento que o tipo dela exige, e esse fechamento traz pelo menos um link para uma página da documentação. O fechamento é `## Próximos passos` ou `## Recursos relacionados`, e um caso de uso fecha com `## Guias deste caso de uso`. Glossário, changelog e hubs de navegação são as exceções, porque cada um já é uma lista de links. - **Sem becos sem saída.** Pelo menos um link do fechamento leva mais fundo no recurso da plataforma da própria página: uma página daquela seção que não seja a visão geral. Um fechamento cujos links apontam todos de volta para onde o leitor veio é um beco sem saída vestido de seção de fechamento. A reciprocidade só é exigida na espinha da seção: a visão geral aponta para toda página da seção, e toda página da seção aponta para a visão geral. Entre quaisquer outras duas páginas o link corre em um sentido só. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/glossario.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/glossario.mdx index bb2c5d67c9..8a8fe30516 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/glossario.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/glossario.mdx @@ -66,7 +66,7 @@ Definições dos termos que a documentação de **** usa. O primeiro glossário de recurso da plataforma é o [glossário do Functions](/pt-br/documentacao/plataforma/functions/glossario/): 22 termos, cada definição apontando sua página canônica. -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-how-to.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-how-to.mdx index c9b39cc3c1..145c227449 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-how-to.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-how-to.mdx @@ -166,7 +166,7 @@ O bucket aparece na lista de buckets. - [Crie regras de request e response](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/rules-engine/): duas tarefas em uma página, cada uma com passos numerados e imperativos. -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-multirrecurso.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-multirrecurso.mdx index c98575c48c..840edf65b6 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-multirrecurso.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-multirrecurso.mdx @@ -133,7 +133,7 @@ Para ativá-lo: O Application Accelerator está ativado na aplicação. ``` -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx index 4eb1329050..4e769827b6 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx @@ -91,7 +91,7 @@ import ProductGuidesSection from '~/components/ProductGuidesSection.astro' - **Escreva descrições que diferenciam.** Diga o que esta página dá que as vizinhas não dão. - **Agrupe quando a lista passa de sete**, pelo que o leitor está tentando fazer. Uma tabela não agrupa: ela ordena em ordem alfabética pelo rótulo de navegação de cada linha, no idioma do leitor. O grupo Recursos de Plataforma da sidebar raiz é a única exceção: todos os recursos da plataforma na ordem em que o leitor os adota, por decisão, porque agrupá-los por intenção traria de volta os pilares aposentados. - **Escolha a forma pelo que o leitor compara.** Destinos variados precisam de uma frase cada, então pedem links agrupados. Um conjunto homogêneo de páginas, comparado por tipo e atualidade, pede a tabela. -- **Nunca escreva uma linha de tabela à mão.** Uma data digitada fica errada na primeira vez que alguém esquece, e é por isso que este é o único lugar em que o guia permite uma data fora de um changelog. +- **Nunca escreva uma linha de tabela à mão.** Uma data digitada fica errada na primeira vez que alguém esquece. As datas da tabela são geradas, e é por isso que [Números e unidades](/pt-br/documentacao/guia-de-estilo/formatacao/numeros/#formate-uma-data-apenas-onde-uma-data-cabe) as permite fora de um changelog. - **Registre a página no catálogo de guias.** Uma página que o catálogo não lista falta no hub. O primeiro recurso da plataforma que o catálogo indica para uma página é o dono dela e dá nome ao tópico dela na seção de Guias. - **Mantenha o hub em dia com a seção.** Atualize o hub na mesma mudança que adiciona uma página. - **Defina `type: homepage` somente em um hub em grade de cards.** Todas as outras páginas omitem o campo. Para mais informações, consulte [Frontmatter](/pt-br/documentacao/guia-de-estilo/convencoes/frontmatter/). @@ -113,7 +113,7 @@ Esta seção reúne os guias para gerenciar buckets e objetos do Object Storage, - [Use um bucket como origem de uma aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/bucket-como-connector/) - Sirva os objetos de um bucket a partir do seu próprio domínio. ``` -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/quickstart.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/quickstart.mdx index 2f98d700ac..265e9983b7 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/quickstart.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/quickstart.mdx @@ -255,7 +255,7 @@ The command returns the Function's ID, which the next stage uses to instantiate Os dois painéis alcançam o mesmo objeto, então o título da etapa e a cadeia de objetos valem para qualquer leitor. -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/referencia.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/referencia.mdx index 0adc22355b..efe9f75c03 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/referencia.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/referencia.mdx @@ -162,7 +162,7 @@ Support can raise the limits marked raisable. Contact the [technical support tea A ausência da coluna é intencional. A separação por plano desses números não foi confirmada, então a tabela não tem coluna de plano, em vez de uma coluna inventada. -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/troubleshooting.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/troubleshooting.mdx index c8a8759679..1a3bb2bbc6 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/troubleshooting.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/troubleshooting.mdx @@ -147,7 +147,7 @@ Para encontrar a regra e liberar as requisições legítimas com o WAF Tuning: A nova allowed rule aparece na aba **Allowed Rules** da página **WAF Rules**. O WAF não bloqueia mais as requisições que correspondem à allowed rule. ``` -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/tutoriais.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/tutoriais.mdx index 7bc8cfeef1..13f5a45725 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/tutoriais.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/tutoriais.mdx @@ -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`. ``` -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/visao-geral.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/visao-geral.mdx index d25118cefc..4e4b26dfef 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/visao-geral.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/visao-geral.mdx @@ -161,7 +161,7 @@ import DocCard from '@aziontech/webkit/doc-card' ``` -## Relacionados +## Recursos relacionados diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/convencoes/paginas-bilingues.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/convencoes/paginas-bilingues.mdx index 157fd3e1e4..ebe3134a10 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/convencoes/paginas-bilingues.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/convencoes/paginas-bilingues.mdx @@ -80,11 +80,12 @@ A lista completa de termos que ficam em inglês dos EUA está em [Terminologia d Três elementos recorrentes se traduzem sempre da mesma forma. Não improvise uma forma nova para eles. -Três nomes de seção têm forma fixa em português do Brasil: +Quatro nomes de seção têm forma fixa em português do Brasil: - `## Prerequisites` vira `## Pré-requisitos`. - `## Next steps` vira `## Próximos passos`. - `## Related resources` vira `## Recursos relacionados`. +- `## Guides in this use case` vira `## Guias deste caso de uso`. As frases padrão de link têm forma fixa, e o verbo é `consulte`: diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/escolha-de-palavras.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/escolha-de-palavras.mdx index 9ef3b39106..392c6b23b9 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/escolha-de-palavras.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/escolha-de-palavras.mdx @@ -70,7 +70,7 @@ Não chame uma tarefa de "simples", "fácil" ou "óbvia", e não suavize um pass Não escreva "por favor". A documentação instrui. Ela não pede. -Não ancore uma página no tempo com "atualmente", "no momento da escrita", "em breve", "agora disponível", "recentemente" ou "novo" como modificador. Todas envelhecem mal, e ninguém volta para corrigir. Nenhum mês ou ano aparece fora de um changelog: diga o que é verdade e deixe o changelog carregar a linha do tempo. Uma data gerada por um passo de build, como a coluna de última atualização em um hub de Guias e tutoriais, é exceção, porque nada escrito à mão envelhece ali. +Não ancore uma página no tempo com "atualmente", "no momento da escrita", "em breve", "agora disponível", "recentemente" ou "novo" como modificador. Todas envelhecem mal, e ninguém volta para corrigir. Nenhum mês ou ano aparece fora de um changelog: diga o que é verdade e deixe o changelog carregar a linha do tempo. [Números e unidades](/pt-br/documentacao/guia-de-estilo/formatacao/numeros/#formate-uma-data-apenas-onde-uma-data-cabe) lista os poucos outros lugares onde uma data cabe, como as datas que um passo de build gera. Escreva "por exemplo" e "isto é", nunca "e.g." nem "i.e.". diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/estrutura-de-frases.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/estrutura-de-frases.mdx index 45bc559f6f..389055c0b7 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/estrutura-de-frases.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/estrutura-de-frases.mdx @@ -16,14 +16,19 @@ A documentação da Azion segue essas regras porque seus leitores correspondem a ## Ajuste o limite de frase ao tipo de conteúdo -O ASD-STE100 define regras mais rígidas para procedimentos do que para descrições. A Azion aplica essa divisão às quatro formas base. - -| Tipo de conteúdo | Modo | Limite por frase | -| --- | --- | --- | -| Tutorial | Procedural | 20 palavras | -| How-to | Procedural | 20 palavras | -| Referência | Descritivo | 25 palavras | -| Explicação | Descritivo | 25 palavras | +O ASD-STE100 define regras mais rígidas para procedimentos do que para descrições. A Azion aplica essa divisão a cada tipo de página de [Escolher um tipo de conteúdo](/pt-br/documentacao/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo/). + +| Forma base | Tipos de página | Modo | Limite por frase | +| --- | --- | --- | --- | +| Tutorial | Quickstart, tutorial | Procedural | 20 palavras | +| How-to | Guia how-to, guia multirrecurso, troubleshooting | Procedural | 20 palavras | +| How-to | Caso de uso | Descritivo | 20 palavras | +| Referência | Visão geral, referência, glossário | Descritivo | 25 palavras | +| Explicação | Conceito, arquitetura | Descritivo | 25 palavras | +| Registro | Changelog | Descritivo | 25 palavras | +| Nenhuma | Hub de navegação | Descritivo | 25 palavras | + +Um caso de uso é How-to pela forma base e descritivo pelo modo. O texto dele descreve um design e deixa cada passo para os guias que ele aponta. Ele mantém o limite de 20 palavras da forma base. Um procedimento tem o limite mais rígido porque o leitor executa cada passo sob pressão. Um passo que o leitor lê errado vira uma ação que falha. Os limites contam apenas frases de texto corrido. Células de tabela, código e saída de comando ficam fora da contagem. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/numeros.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/numeros.mdx index e871df7c6c..5e0ef53504 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/numeros.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/numeros.mdx @@ -49,7 +49,12 @@ Escreva `primeiro` e `segundo` por extenso. Em algarismo, escreva `1º`, nunca ` ## Formate uma data apenas onde uma data cabe -Datas aparecem em changelogs e em nenhum outro lugar, o que [Escolha de palavras](/pt-br/documentacao/guia-de-estilo/escrita/escolha-de-palavras/) declara como regra. Uma data em qualquer outro lugar envelhece a página. +Uma data envelhece a página onde está, então o texto escrito à mão não traz nenhuma, como [Escolha de palavras](/pt-br/documentacao/guia-de-estilo/escrita/escolha-de-palavras/) exige. Uma data cabe em apenas quatro lugares: + +- **Um changelog**, onde cada entrada é uma data. +- **Uma data gerada**: a linha de última atualização no cabeçalho de toda página e a coluna de última atualização de um hub de Guias e tutoriais. Um passo de build escreve essa data, então ela nunca envelhece. +- **Um contrato datado**, que registra o que era verdade no dia em que entrou em vigor, como [Terminologia da documentação](/pt-br/documentacao/guia-de-estilo/escrita/terminologia/#mantenha-nomes-historicos-em-documentos-historicos) explica. +- **A data de desligamento da API v3**, que aparece só no snippet `versionDeprecated` e em Migração para API v4, como [Componentes](/pt-br/documentacao/guia-de-estilo/componentes/#avisos-de-versao) define. Onde a data é permitida, escreva o mês por extenso: `10 de julho de 2026`. O inglês dos EUA usa a ordem mês, dia, ano: `July 10, 2026`. From 00dbcc51bab7ac9e04ea8d40f20dd56d8dc62246 Mon Sep 17 00:00:00 2001 From: Bruno Germano Date: Tue, 10 Nov 2026 15:54:00 -0300 Subject: [PATCH 2/8] docs(style-guide): split the long sentences of the content pages --- .../docs/en/pages/style-guide/components.mdx | 8 +++---- .../pages/style-guide/content/changelog.mdx | 2 +- .../content/choose-a-content-type.mdx | 2 +- .../style-guide/content/how-to-guides.mdx | 2 +- .../content/information-architecture.mdx | 24 ++++++++++++++----- .../style-guide/content/navigation-hubs.mdx | 6 ++--- .../en/pages/style-guide/content/overview.mdx | 10 ++++---- .../pages/guia-de-estilo/componentes.mdx | 8 +++---- .../conteudo/arquitetura-de-informacao.mdx | 24 ++++++++++++++----- .../conteudo/escolher-um-tipo-de-conteudo.mdx | 2 +- .../guia-de-estilo/conteudo/guias-how-to.mdx | 2 +- .../conteudo/hubs-de-navegacao.mdx | 6 ++--- .../guia-de-estilo/conteudo/visao-geral.mdx | 10 ++++---- 13 files changed, 65 insertions(+), 41 deletions(-) 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 5c3ad62da4..3aa1f69aff 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 @@ -323,7 +323,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/). 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 ea5426f74b..84f44d6673 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 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 c488664a10..189a93e454 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 @@ -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 a filterable 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 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 5a2ccf66f0..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 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 091ab249d7..852e3f55bf 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. 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, not a page. [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. 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 stays at the root of Platform Resources: Functions, Object Storage, SQL Database, KV Store, and AI Inference. A standalone service stays there too: Edge DNS, Data Stream, and 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, not a page. [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. 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 8d68c1dc6e..c34df42bcd 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 @@ -49,11 +49,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 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 hub of its own. ## Template @@ -89,7 +89,7 @@ import ProductGuidesSection from '~/components/ProductGuidesSection.astro' - **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 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. 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. - **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. 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 e172067412..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. 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 33cbf764e8..8608e80bef 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 @@ -163,7 +163,7 @@ 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. - **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 @@ -323,7 +323,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/). 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 8c41691c1e..3f2f380cbd 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. 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, não uma página. [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. 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: + +- 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: 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 fica na raiz de Recursos de Plataforma: Functions, Object Storage, SQL Database, KV Store e AI Inference. Um serviço autônomo também fica ali: Edge DNS, Data Stream e Orchestrator. 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, 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, não uma página. [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. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.mdx index 192409e7e6..57f9eb13ff 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.mdx @@ -41,7 +41,7 @@ Um tipo de página é uma forma base mais um lugar na [arquitetura de informaç | [Glossário](/pt-br/documentacao/guia-de-estilo/conteudo/glossario/) | Referência | Sim | Definir os termos que a documentação da seção usa, em uma tabela filtrável | | [Hub de navegação](/pt-br/documentacao/guia-de-estilo/conteudo/hubs-de-navegacao/) | Nenhuma | Não | Levar o leitor mais fundo na documentação. Links mais uma frase de orientação | -Obrigatório por seção significa obrigatório em toda seção de recurso da plataforma. Um recurso da plataforma aninhado como dropdown em outro 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; toda outra página que ele teria é uma seção das páginas do recurso. A regra de aninhamento está em [Arquitetura de informação](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura-de-informacao/#recursos-da-plataforma-aninhados). +Obrigatório por seção significa obrigatório em toda seção de recurso da plataforma. Um recurso da plataforma aninhado como dropdown em outro 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. Toda outra página que ele teria é uma seção das páginas do recurso. A regra de aninhamento está em [Arquitetura de informação](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura-de-informacao/#recursos-da-plataforma-aninhados). ## Slots não são tipos diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-how-to.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-how-to.mdx index 145c227449..449c105897 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-how-to.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/guias-how-to.mdx @@ -39,7 +39,7 @@ Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo **Componentes opcionais** -- **Tabs por interface**: quando uma tarefa roda em mais de uma interface, a página declara a faixa de tabs uma vez, a primeira coisa sob `## Pré-requisitos`, e cada tarefa carrega um bloco da mesma store só com painéis, que renderiza essa faixa acima dos seus painéis. Console primeiro, um procedimento completo por painel, e cada painel abre com o nome da interface como título, um nível abaixo da sua seção. +- **Tabs por interface**: quando uma tarefa roda em mais de uma interface, a página declara a faixa de tabs uma vez, como a primeira coisa sob `## Pré-requisitos`. Cada tarefa carrega um bloco da mesma store só com painéis, que renderiza essa faixa acima dos seus painéis. Console primeiro, um procedimento completo por painel, e cada painel abre com o nome da interface como título, um nível abaixo da sua seção. - **Um aside** com o caminho alternativo, quando a tarefa genuinamente ramifica. ## Template diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx index 4e769827b6..adcef0feff 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx @@ -49,11 +49,11 @@ O padrão. Use quando os destinos são diferentes entre si e o leitor precisa de ### Forma 2: uma tabela -Use quando o hub lista um conjunto homogêneo e o leitor escolhe por tipo e atualidade, e não por descrição. O slot Guias e tutoriais tem essa forma, porque cada linha é um how-to ou um tutorial do mesmo recurso da plataforma e uma frase por linha repetiria o título da página. +Use quando o hub lista um conjunto homogêneo e o leitor escolhe por tipo e atualidade, e não por descrição. O slot Guias e tutoriais tem essa forma, porque cada linha é um how-to ou um tutorial do mesmo recurso da plataforma. Uma frase por linha só repetiria o título da página. - **Corpo**: um ``, sem títulos `##` e sem grupos. - **Colunas**: nome, tipo, última atualização. -- **A tabela é gerada, nunca digitada.** Uma página aparece quando o catálogo de guias a marca com o recurso da plataforma, o tipo vem do catálogo e a data vem da última alteração da página, então o hub não fica dessincronizado das páginas que lista. O hub de um recurso também lista os guias dos recursos da plataforma aninhados nele; um recurso da plataforma aninhado não tem hub próprio. +- **A tabela é gerada, nunca digitada.** Uma página aparece quando o catálogo de guias a marca com o recurso da plataforma. O tipo vem do catálogo, e a data vem da última alteração da página. Por isso o hub não fica dessincronizado das páginas que lista. O hub de um recurso também lista os guias dos recursos da plataforma aninhados nele; um recurso da plataforma aninhado não tem hub próprio. ## Template @@ -89,7 +89,7 @@ import ProductGuidesSection from '~/components/ProductGuidesSection.astro' - **Nenhum fechamento e nenhum outro texto.** Uma frase de orientação; a explicação vai em uma [página de conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/). - **Faça cada link justificar o seu lugar.** Um hub é julgado pelo que ele deixa de fora; um hub que lista tudo não hierarquiza nada. - **Escreva descrições que diferenciam.** Diga o que esta página dá que as vizinhas não dão. -- **Agrupe quando a lista passa de sete**, pelo que o leitor está tentando fazer. Uma tabela não agrupa: ela ordena em ordem alfabética pelo rótulo de navegação de cada linha, no idioma do leitor. O grupo Recursos de Plataforma da sidebar raiz é a única exceção: todos os recursos da plataforma na ordem em que o leitor os adota, por decisão, porque agrupá-los por intenção traria de volta os pilares aposentados. +- **Agrupe quando a lista passa de sete**, pelo que o leitor está tentando fazer. Uma tabela não agrupa: ela ordena em ordem alfabética pelo rótulo de navegação de cada linha, no idioma do leitor. O grupo Recursos de Plataforma da sidebar raiz é a única exceção: ele lista todos os recursos da plataforma na ordem em que o leitor os adota. Essa ordem é uma decisão, porque agrupá-los por intenção traria de volta os pilares aposentados. - **Escolha a forma pelo que o leitor compara.** Destinos variados precisam de uma frase cada, então pedem links agrupados. Um conjunto homogêneo de páginas, comparado por tipo e atualidade, pede a tabela. - **Nunca escreva uma linha de tabela à mão.** Uma data digitada fica errada na primeira vez que alguém esquece. As datas da tabela são geradas, e é por isso que [Números e unidades](/pt-br/documentacao/guia-de-estilo/formatacao/numeros/#formate-uma-data-apenas-onde-uma-data-cabe) as permite fora de um changelog. - **Registre a página no catálogo de guias.** Uma página que o catálogo não lista falta no hub. O primeiro recurso da plataforma que o catálogo indica para uma página é o dono dela e dá nome ao tópico dela na seção de Guias. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/visao-geral.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/visao-geral.mdx index 4e4b26dfef..24380512c3 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/visao-geral.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/visao-geral.mdx @@ -38,8 +38,8 @@ Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é - **Bloco de definição**, em três partes. Primeiro o recurso da plataforma: `**** é um que .` Essa frase nomeia o recurso, declara a classe dele e se sustenta sozinha. A classe é `recurso da plataforma`, tanto na visão geral de uma seção quanto na de um recurso da plataforma aninhado, conforme [Terminologia da documentação](/pt-br/documentacao/guia-de-estilo/escrita/terminologia/#declare-a-classe-de-um-elemento-da-azion). A frase nunca depende de um conceito que o leitor ainda não conheceu, como faz "executa esse código". Depois o conceito: uma ou duas frases dizendo o que é a classe da coisa, para um leitor que nunca usou uma, com qualquer termo do mercado definido no próprio texto. Depois uma frase nomeando as tarefas concretas para as quais as pessoas o usam, no vocabulário do leitor, fechando o bloco: `Use para fazer A, executar B ou servir C.` Uma lista de benefícios em bullets é a forma mais fraca dessa frase: parece um folheto e custa uma tela. - **CTAs**: um `DocButton` primário com o rótulo **Primeiros passos** e um secundário com o rótulo `Referência de `. -- **O mecanismo**: quando uma requisição, um evento ou um job atravessa mais de dois objetos antes de o recurso da plataforma executar, essa cadeia como um diagrama `mermaid`, seguido de um percurso numerado com no máximo seis itens. Abra com o que o leitor presumiria errado e diga na mesma frase o que acontece no lugar: `Criar uma Function não a expõe: uma requisição só chega a ela por uma Function Instance que uma regra invoca.` -- **A amostra**: quando o recurso da plataforma tem um artefato de código, um objeto de configuração ou uma requisição, um exemplo completo e mínimo dele, inteiro, logo depois do mecanismo, ou logo depois dos CTAs quando a página não tem a seção de mecanismo. Dois a quatro bullets nomeiam as partes, e uma frase diz qual conhecimento prévio se aproveita. Um recurso da plataforma sem esse artefato pula a seção em vez de inventar uma. +- **O mecanismo**: quando uma requisição, um evento ou um job atravessa mais de dois objetos antes de o recurso da plataforma executar, essa cadeia como um diagrama `mermaid`. Um percurso numerado com no máximo seis itens vem depois do diagrama. Abra com o que o leitor presumiria errado e diga na mesma frase o que acontece no lugar: `Criar uma Function não a expõe: uma requisição só chega a ela por uma Function Instance que uma regra invoca.` +- **A amostra**: quando o recurso da plataforma tem um artefato de código, um objeto de configuração ou uma requisição, um exemplo completo e mínimo dele, inteiro. Ela fica logo depois do mecanismo, ou logo depois dos CTAs quando a página não tem a seção de mecanismo. Dois a quatro bullets nomeiam as partes, e uma frase diz qual conhecimento prévio se aproveita. Um recurso da plataforma sem esse artefato pula a seção em vez de inventar uma. - **Os recursos**: somente em um recurso da plataforma que tem outros recursos da plataforma aninhados nele. Para cada aninhado, diga o que ele faz neste recurso e quando o leitor o ativa, em uma ou duas frases, a primeira declarando a classe dele: ` é um recurso da plataforma que…`. Depois aponte para onde o leitor vai para usá-lo. É o que o leitor precisa para decidir se abre o recurso da plataforma aninhado, nunca a lista de features. - **As fronteiras**: um único bloco compacto de bullets com introduções em negrito — linguagens, APIs, frameworks, integrações e os principais limites. Um bloco, não uma seção por feature. - **Seções de capacidade**: só para uma capacidade que muda o que o leitor construiria, no máximo três. Uma capacidade que cabe em uma frase e um link pertence ao bloco de fronteiras ou ao roteador. @@ -110,10 +110,10 @@ Use para , ou . - **Conte para a frente a relação entre dois recursos da plataforma.** Quem faz a ligação é o sujeito, e a frase segue a ordem em que as coisas acontecem: `Uma Application recebe as requisições de um Workload depois que o deployment desse Workload define essa Application.` A frase `Uma Application recebe as requisições dos Workloads cujo deployment a define.` começa pelo fim e deixa dois pronomes apontando para trás. O verbo leva o objeto por extenso: `define essa Application`, nunca `a define`. - **Escolha o conceito com cuidado.** Vários elementos da Azion fazem coisas diferentes sob um mesmo nome. Quando um conceito de mercado cobre tudo o que o recurso da plataforma faz, explique esse conceito. Quando nenhum cobre, explique cada coisa em uma frase. - **Nomeie o recurso da plataforma que fornece um conceito.** Quando outro recurso da plataforma fornece uma dessas coisas, a frase que explica o termo de mercado nomeia a instância dele logo depois do termo e mantém a explicação: `Uma função serverless é uma Function, um código executado sob demanda a cada requisição, sem um servidor para você provisionar.` -- **Corte do bloco de definição o que o leitor não precisa.** Quatro tipos de frase saem: o contexto que o recurso da plataforma não muda, como a delegação de um domínio a partir do registro; o passo que o leitor já presume, como um proxy abrindo a própria conexão com a origem; um ponto que o bloco já fez; e um contraste com algo que a página não cobre, como `Um log é a visão oposta.` +- **Corte do bloco de definição o que o leitor não precisa.** Quatro tipos de frase saem. O primeiro é o contexto que o recurso da plataforma não muda, como a delegação de um domínio a partir do registro. O segundo é um passo que o leitor já presume, como um proxy que abre a própria conexão com a origem. O terceiro é um ponto que o bloco já fez. O quarto é um contraste com algo que a página não cobre, como `Um log é a visão oposta.` - **Um uso diz o que este recurso da plataforma acrescenta.** A frase de usos nomeia as tarefas que este recurso da plataforma faz e outro não. Em Functions, o uso é "bloquear requisições com a sua própria lógica", porque o Firewall já bloqueia requisições por regra. Um recurso da plataforma de segurança nomeia o padrão público que as páginas dele documentam, como o OWASP Top 10. - **Nomeie o recurso da plataforma na primeira frase, e nunca abra com o contexto do problema.** Uma frase de conceito explica um mecanismo. Uma frase sobre a importância do problema não explica nada. -- **Organize pelas perguntas do leitor, não pela sua lista de features.** As seções respondem, na ordem: o que o recurso da plataforma da Azion faz, o que é a classe da coisa, como isso é chamado, o que eu escrevo, quais produtos ele hospeda, o que faz e onde para, para onde vou agora. Um sumário que reproduz a lista de features do recurso da plataforma é um catálogo: responde "o que vendemos" em vez de "o que estou decidindo". +- **Organize pelas perguntas do leitor, não pela sua lista de features.** As seções respondem a sete perguntas, na ordem. As três primeiras são o que o recurso da plataforma da Azion faz, o que é a classe da coisa e como isso é chamado. As três seguintes são o que eu escrevo, quais produtos ele hospeda, e o que ele faz e onde para. A última é para onde vou agora. Um sumário que reproduz a lista de features do recurso da plataforma é um catálogo: responde "o que vendemos" em vez de "o que estou decidindo". - **As perguntas moldam as seções; elas nunca viram títulos.** Um título é uma expressão nominal curta, nunca uma pergunta: `Estrutura de uma função`, não `Como é uma função`. - **Desenhe o diagrama a partir da sequência documentada.** Um diagrama de uma sequência que a documentação já descreve em prosa é uma mudança de notação, não um fato novo. Cada nó e cada seta corresponde a um passo que o recurso da plataforma executa, e o percurso numerado carrega o significado se a figura não renderizar. - **Envie o leitor para o [Quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/)**, nos CTAs e de novo no roteador. @@ -121,7 +121,7 @@ Use para , ou . ## Exemplos -Este trecho, em inglês dos EUA, da visão geral de **Functions** mostra o bloco de definição nas suas três partes e a amostra, e deixa o mecanismo de fora. A primeira frase nomeia o recurso da plataforma, declara a classe dele e diz o que ele faz na Azion; as seguintes explicam o que é uma função para um leitor que nunca usou uma; a frase de usos fecha o bloco; a amostra mostra o artefato em vez de descrevê-lo: +Este trecho, em inglês dos EUA, da visão geral de **Functions** mostra o bloco de definição nas suas três partes e a amostra, e deixa o mecanismo de fora. A primeira frase nomeia o recurso da plataforma, declara a classe dele e diz o que ele faz na Azion. As seguintes explicam o que é uma função para um leitor que nunca usou uma. A frase de usos fecha o bloco, e a amostra mostra o artefato em vez de descrevê-lo: ```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. From 4c93637d0108e37eb4bd56cd3c1cce9e8dad300b Mon Sep 17 00:00:00 2001 From: Bruno Germano Date: Tue, 10 Nov 2026 15:57:28 -0300 Subject: [PATCH 3/8] docs(style-guide): split the remaining sentences over 30 words --- .../pages/style-guide/content/quickstart.mdx | 6 +++--- .../pages/style-guide/content/tutorials.mdx | 2 +- .../pages/style-guide/content/use-cases.mdx | 16 +++++++-------- .../style-guide/conventions/bilingual.mdx | 6 +++--- .../style-guide/how-we-docs/docs-as-code.mdx | 2 +- .../pages/style-guide/writing/procedures.mdx | 2 +- .../pages/style-guide/writing/terminology.mdx | 10 +++++----- .../pages/style-guide/writing/word-choice.mdx | 2 +- .../como-documentamos/docs-as-code.mdx | 2 +- .../pages/guia-de-estilo/componentes.mdx | 4 ++-- .../conteudo/arquitetura-de-informacao.mdx | 6 +++--- .../guia-de-estilo/conteudo/arquitetura.mdx | 4 ++-- .../guia-de-estilo/conteudo/casos-de-uso.mdx | 20 +++++++++---------- .../guia-de-estilo/conteudo/glossario.mdx | 2 +- .../guia-de-estilo/conteudo/quickstart.mdx | 8 ++++---- .../guia-de-estilo/conteudo/tutoriais.mdx | 2 +- .../guia-de-estilo/conteudo/visao-geral.mdx | 4 ++-- .../convencoes/paginas-bilingues.mdx | 8 ++++---- .../escrita/escolha-de-palavras.mdx | 2 +- .../guia-de-estilo/escrita/procedimentos.mdx | 2 +- .../guia-de-estilo/escrita/terminologia.mdx | 12 +++++------ .../guia-de-estilo/formatacao/codigo.mdx | 2 +- 22 files changed, 62 insertions(+), 62 deletions(-) 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 e9855c5e90..c38b4d5894 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, not a page. 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 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 2ffa8eb51d..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. 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 bf9548b673..79b4ee3cef 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 carries what a reader needs to understand and decide. That is 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 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. @@ -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. 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 7427970531..4b2ed1be09 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. 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 dc0788dbbe..bea3465e74 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 @@ -90,7 +90,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/terminology.mdx b/apps/docs/src/content/docs/en/pages/style-guide/writing/terminology.mdx index 077e55e7cf..d45590b237 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. Two examples 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.` 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 e3b094f708..506928b3fb 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 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 8608e80bef..dcc4fbb4b3 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 @@ -161,7 +161,7 @@ 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. - **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 (`==>`). @@ -267,7 +267,7 @@ import DocUpdate from '@aziontech/webkit/doc-update' - Sem diretiva client. Linhas em branco ao redor do markdown interno são obrigatórias. - 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 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 3f2f380cbd..fe4bfc817e 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 @@ -59,16 +59,16 @@ Um recurso da plataforma aninhado em outro é uma linha dropdown dentro da seç - Connectors: Load Balancer, Origin Shield e Live Ingest. - Workloads: Certificate Manager, Custom Pages e DDoS Protection. -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. 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: +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. 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: 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 fica na raiz de Recursos de Plataforma: Functions, Object Storage, SQL Database, KV Store e AI Inference. Um serviço autônomo também fica ali: Edge DNS, Data Stream e Orchestrator. Uma feature é uma página dentro do recurso da plataforma dela, nunca um dropdown. +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 fica na raiz de Recursos de Plataforma: Functions, Object Storage, SQL Database, KV Store e AI Inference. Um serviço autônomo também fica ali: Edge DNS, Data Stream e Orchestrator. 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, 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, não uma página. [Páginas de quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) tem o teste. +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, não uma página. [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. 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 c0f3cd234a..71ad192537 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 @@ -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. 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 78ee140d7c..52401cf812 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 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. @@ -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