From 48b789891227760c2af9c99c431e4436c9095b92 Mon Sep 17 00:00:00 2001 From: Marcus Souza Date: Fri, 6 Nov 2026 11:55:08 -0300 Subject: [PATCH 1/5] docs(style-guide): flatten the closing rows and give nested Products a mechanism page Bring the structure rules in line with the shipped sections, in en and pt-br: - Limits, Pricing, and Changelog are rows of a Platform Resource section, at the same level as the others; no Management parent. - The Guides and tutorials hub lists name, type, and last updated, and sorts alphabetically by navigation label, not by date or title. - A nested Product's Reference group opens with its mechanism page, a concept page titled for the mechanism; the resource's How it works keeps a short section that links it. Live Ingest joins the Connectors list. - Troubleshooting groups a nested Product's symptoms under one section, with each symptom one level down. --- .../docs/en/pages/style-guide/components.mdx | 2 +- .../style-guide/content/choose-a-content-type.mdx | 2 +- .../docs/en/pages/style-guide/content/concept.mdx | 2 ++ .../content/information-architecture.mdx | 13 ++++++------- .../pages/style-guide/content/navigation-hubs.mdx | 6 +++--- .../pages/style-guide/content/troubleshooting.mdx | 2 +- .../docs/pt-br/pages/guia-de-estilo/componentes.mdx | 2 +- .../conteudo/arquitetura-de-informacao.mdx | 13 ++++++------- .../pages/guia-de-estilo/conteudo/conceito.mdx | 2 ++ .../conteudo/escolher-um-tipo-de-conteudo.mdx | 2 +- .../guia-de-estilo/conteudo/hubs-de-navegacao.mdx | 6 +++--- .../guia-de-estilo/conteudo/troubleshooting.mdx | 2 +- 12 files changed, 28 insertions(+), 26 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 88e457e8d9..27d6792e7f 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 @@ -344,7 +344,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 Product nested in it. - The date is the page's last change, filled in for you. Never write it by hand. - The type column shows each page's content type, in the reader's language. -- Rows sort by title. +- 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/choose-a-content-type.mdx b/apps/docs/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx index d63a1422e6..4d2fef4448 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 Product nested as a dropdown in a Platform Resource needs only its reference pages, plus 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-products). +Required per section means required in every Platform Resource section. A Product nested as a dropdown in a 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; 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-products). ## Slots are not kinds 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 82abc0e508..6507c42aef 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 @@ -41,6 +41,8 @@ Descriptive: 25 words per sentence, active voice, passive only where the actor i The title is `How works`, `About `, or a short noun phrase: `How Tiered Cache works`. +A mechanism page is the concept page of one Product nested in a Platform Resource. It opens the Product's Reference group in the sidebar, and its title names the mechanism, such as `Scoring and modes` for WAF. It is never titled `How works`, because the resource's How it works page already introduces the Product in a `## ` section that links here. + **Required components** - **Opening move**: a declarative statement of how the system behaves, in the reader's terms before any Azion object is named. Never `This page explains`. 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 5872aab5ad..16421e62e6 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 @@ -36,16 +36,15 @@ A Platform Resource type with a section of its own (Workloads, Edge DNS, Applica 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, last updated, and difficulty, 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. +**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 difficulty comes from the page's `difficulty` frontmatter field, 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, so the hub 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. -Other rows may group the same way. A group is a menu parent, not a page, and it stays one level deep. Two modes exist: +Other rows may group the same way. A group is a menu parent, not a page, and it stays one level deep. It holds one slot's pages under the slot's standard name. Reference is the canonical case. Quickstart groups the same way in the one case it still splits: a first run an interface cannot share. -- **Fixed groups** hold one slot's pages under the slot's standard name. Reference is the canonical case. Quickstart groups the same way in the one case it still splits: a first run an interface cannot share. -- **Same-type groups** hold related closing pages under one thematic parent. **Management** holds Limits, Pricing, and Changelog: the pages the reader consults about running the Platform Resource. +Limits, Pricing, and Changelog are rows of the section, at the same level as every other row, in slot order. They never share a parent such as **Management**. Do not group rows that read fine flat. A parent costs the reader one click on every visit, so a group must pay for itself. @@ -53,7 +52,7 @@ A feature with its own surface repeats the pattern one level down: Tiered Cache ## Nested Products -A Product enabled on a Platform Resource is a dropdown row inside the resource 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 and Origin Shield inside Connectors; Certificate Manager, Custom Pages, and DDoS Protection inside Workloads. The Product 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 resource's Overview links. Everything else the reader needs about it is written once, in the resource's pages: what the Product does and when to turn it on in the resource's Overview, how it works in the resource's How it works, its limits, practices, and symptoms in the resource's Limits, Best practices, and Troubleshooting, its terms in the resource's Glossary, and its guides in the resource's hub. +A Product enabled on a Platform Resource is a dropdown row inside the resource 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. The Product 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 resource's Overview links. When the Product 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 resource's pages: what the Product does and when to turn it on in the resource's Overview, a `## ` section in the resource's How it works that introduces the Product and links its mechanism page, its limits, practices, and symptoms in the resource's Limits, Best practices, and Troubleshooting, its terms in the resource's Glossary, and its guides in the resource's hub. A Product nests when its configuration lives in the resource's own settings or rules: a flag in `modules`, a Rules Engine behavior, or a field of the resource. A Product or 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 Product, never a dropdown. A Platform Resource type nested in another, such as Certificate Manager and Custom Pages in Workloads, follows the same rule. @@ -65,7 +64,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 Product needs only its reference pages, plus 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 Product 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. - **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 e6b71fa192..aef4e22000 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,7 +49,7 @@ 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 effort 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 and a per-row sentence would repeat the page title. - **Body**: one ``, no `##` headings and no groups. - **Columns**: name, type, last updated. @@ -89,8 +89,8 @@ 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, newest first. 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 kind of page, compared on effort and freshness, takes the table. +- **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. - **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. 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 62f955eb8e..8aabbde1bd 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 @@ -34,7 +34,7 @@ The title is shaped `Troubleshoot `: `Troubleshoot WAF **Required components** - **Opening move**: one scope sentence naming the Platform Resource and the class of symptoms the page covers. -- **Symptom sections**: one `##` per symptom, each fully self-contained and readable in any order. +- **Symptom sections**: one `##` per symptom, each fully self-contained and readable in any order. On a Platform Resource with nested Products, the resource's symptoms come first, then one `## ` section per nested Product, with its symptoms as `###`. The rules for a symptom section apply to each `###` in the same way. - **Symptom headings**: a noun phrase stating the observable behavior, quoting the error string verbatim as plain text: `## 403 Forbidden on legitimate requests`. No inline code in a heading: backticks render a code chip that breaks the heading line. - **The symptom**: what the reader sees, in one or two sentences, first in every section. - **The cause**: what produces the symptom. 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 834f557c0d..adf6a4fd69 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 @@ -344,7 +344,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 produto aninhado nela. - A data é a da última alteração da página, preenchida automaticamente. Nunca escreva a data à mão. - A coluna de tipo mostra o tipo de conteúdo de cada página, no idioma do leitor. -- As linhas ordenam por título. +- As linhas ordenam em ordem alfabética pelo rótulo de navegação de cada página, no idioma do leitor, nunca por data. A coluna de nome mostra esse rótulo, não o título da página. --- diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx index 3e2ef054cd..efc5361036 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 @@ -36,16 +36,15 @@ Um tipo de recurso da plataforma com seção própria (Workloads, Edge DNS, Appl 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, última atualização e dificuldade, 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. +**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 a dificuldade vem do campo `difficulty` do frontmatter da 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, então 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. -Outras linhas podem se agrupar da mesma forma. Um grupo é um pai da sidebar, não uma página, e fica em um único nível. Dois modos existem: +Outras linhas podem se agrupar da mesma forma. Um grupo é um pai da sidebar, não uma página, e fica em um único nível. Ele guarda as páginas de um slot sob o nome padrão do slot. Referência é o caso canônico. O slot Primeiros passos se agrupa da mesma forma no único caso em que ainda se divide: um primeiro uso que a interface não consegue compartilhar. -- **Grupos fixos** guardam as páginas de um slot sob o nome padrão do slot. Referência é o caso canônico. O slot Primeiros passos se agrupa da mesma forma no único caso em que ainda se divide: um primeiro uso que a interface não consegue compartilhar. -- **Grupos de mesmo tipo** guardam páginas de fechamento relacionadas sob um pai temático. **Gerenciamento** guarda Limites, Preços e Changelog: as páginas que o leitor consulta sobre a operação do recurso da plataforma. +Limites, Preços e Changelog são linhas da seção, no mesmo nível de todas as outras, na ordem dos slots. Elas nunca dividem um pai como **Gerenciamento**. Não agrupe linhas que funcionam bem planas. Um pai custa um clique ao leitor em cada visita, então um grupo precisa se pagar. @@ -53,7 +52,7 @@ Uma feature com superfície própria repete o padrão um nível abaixo: Tiered C ## Produtos aninhados -Um produto habilitado em um recurso da plataforma é uma linha dropdown dentro da seção do recurso, 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 e Origin Shield dentro de Connectors; Certificate Manager, Custom Pages e DDoS Protection dentro de Workloads. O produto 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 recurso aponta. Todo o resto que o leitor precisa saber sobre ele é escrito uma vez, nas páginas do recurso: o que o produto faz e quando ativá-lo na visão geral do recurso, como ele funciona na página Como funciona do recurso, os limites, as práticas e os sintomas nas páginas Limites, Boas práticas e Troubleshooting do recurso, os termos no glossário do recurso e os guias no hub do recurso. +Um produto habilitado em um recurso da plataforma é uma linha dropdown dentro da seção do recurso, 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. O produto 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 recurso aponta. Quando o produto 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 recurso: o que o produto faz e quando ativá-lo na visão geral do recurso, uma seção `## ` na página Como funciona do recurso que apresenta o produto 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 recurso, os termos no glossário do recurso e os guias no hub do recurso. Um produto se aninha quando a configuração dele vive nas configurações ou nas regras do próprio recurso: uma flag em `modules`, um behavior do Rules Engine ou um campo do recurso. Um produto ou recurso 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 produto, nunca um dropdown. Um tipo de recurso da plataforma aninhado em outro, como Certificate Manager e Custom Pages em Workloads, segue a mesma regra. @@ -65,7 +64,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 produto aninhado precisa somente das páginas de referência, 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 produto 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. - **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/conceito.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/conceito.mdx index bf1d8eb1d8..34f08fc434 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 @@ -41,6 +41,8 @@ Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o ator é ge O título é `Como funciona`, `Sobre ` ou uma frase nominal curta: `Como o Tiered Cache funciona`. +Uma página de mecanismo é a página de conceito de um produto aninhado em um recurso da plataforma. Ela abre o grupo Referência do produto na sidebar, e o título dela nomeia o mecanismo, como `Score e modos` para o WAF. Ela nunca tem o título `Como o funciona`, porque a página Como funciona do recurso já apresenta o produto em uma seção `## ` que aponta para ela. + **Componentes obrigatórios** - **Abertura**: uma declaração de como o sistema se comporta, nos termos do leitor antes de nomear qualquer objeto da Azion. Nunca `Esta página explica`. 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 25d0aecdc8..55285a9306 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 produto aninhado como dropdown em um recurso da plataforma precisa somente das páginas de referência, 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/#produtos-aninhados). +Obrigatório por seção significa obrigatório em toda seção de recurso da plataforma. Um produto aninhado como dropdown em um recurso da plataforma 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/#produtos-aninhados). ## Slots não são tipos 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 da70a17d99..5e5c78ab97 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,7 +49,7 @@ 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 esforço 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 e uma frase por linha repetiria o título da página. - **Corpo**: um ``, sem títulos `##` e sem grupos. - **Colunas**: nome, tipo, última atualização. @@ -89,8 +89,8 @@ 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, da mais recente para a mais antiga. 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 único tipo de página, comparado por esforço e atualidade, pede a tabela. +- **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. - **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. 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 d7bcf4a4f5..46dffbc2ab 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 @@ -34,7 +34,7 @@ O título tem a forma `Solucione problemas de `: **Componentes obrigatórios** - **Abertura**: uma frase de escopo que nomeia o recurso da plataforma e a classe de sintomas que a página cobre. -- **Seções de sintoma**: uma seção `##` por sintoma, cada uma autossuficiente e legível em qualquer ordem. +- **Seções de sintoma**: uma seção `##` por sintoma, cada uma autossuficiente e legível em qualquer ordem. Em um recurso da plataforma com produtos aninhados, os sintomas do recurso vêm primeiro, depois uma seção `## ` por produto aninhado, com os sintomas dele em `###`. As regras de uma seção de sintoma valem da mesma forma para cada `###`. - **Títulos de sintoma**: uma frase nominal que declara o comportamento observável, com a mensagem de erro citada literalmente como texto simples: `## 403 Forbidden em requisições legítimas`. Sem código inline em título: as crases renderizam um chip de código que quebra a linha do título. - **O sintoma**: o que o leitor vê, em uma ou duas frases, primeiro em cada seção. - **A causa**: o que produz o sintoma. From 922dfb3b6432d51cceb137cd799325a627a12a51 Mon Sep 17 00:00:00 2001 From: Marcus Souza Date: Fri, 6 Nov 2026 11:55:21 -0300 Subject: [PATCH 2/5] docs(style-guide): state the class of an Azion element and keep instance names in English Terminology and the Overview pattern, in en and pt-br: - The sentence that defines an Azion element states its class: Platform Resource, Product, or Feature with its scope. A new Terminology section classifies section roots, nested Products, nested Platform Resources, and Features. The Overview template, its Functions example, and its resources entries carry the class. - The Overview mechanism opens with what the reader would assume wrong and says what happens instead. - A sentence about where the platform answers names the data center nearest to the user, never a distance. - A page ties the instance to its Platform Resource where it first appears: "An application is the object you create in Applications." - In Brazilian Portuguese, the instance keeps its US English name in lowercase (a application, a function, o workload, o connector, o firewall, o deployment, o bucket). The Bilingual pages substitution and the guide's own pt-br examples follow it. --- .../en/pages/style-guide/content/concept.mdx | 2 +- .../en/pages/style-guide/content/overview.mdx | 16 +++---- .../style-guide/conventions/bilingual.mdx | 2 +- .../pages/style-guide/writing/terminology.mdx | 36 ++++++++++++-- .../como-documentamos/docs-as-code.mdx | 6 +-- .../pages/guia-de-estilo/componentes.mdx | 6 +-- .../guia-de-estilo/conteudo/arquitetura.mdx | 10 ++-- .../guia-de-estilo/conteudo/casos-de-uso.mdx | 4 +- .../guia-de-estilo/conteudo/conceito.mdx | 2 +- .../conteudo/escolher-um-tipo-de-conteudo.mdx | 2 +- .../conteudo/guias-multirrecurso.mdx | 14 +++--- .../guia-de-estilo/conteudo/quickstart.mdx | 2 +- .../guia-de-estilo/conteudo/visao-geral.mdx | 18 +++---- .../convencoes/paginas-bilingues.mdx | 2 +- .../escrita/estrutura-de-frases.mdx | 8 ++-- .../guia-de-estilo/escrita/procedimentos.mdx | 4 +- .../guia-de-estilo/escrita/terminologia.mdx | 48 +++++++++++++++---- .../guia-de-estilo/formatacao/pontuacao.mdx | 2 +- .../pages/guia-de-estilo/formatacao/texto.mdx | 2 +- 19 files changed, 121 insertions(+), 65 deletions(-) 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 6507c42aef..017034d234 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 @@ -108,7 +108,7 @@ behaves, and what it costs.> This excerpt of a concept page for Tiered Cache shows the opening move, the roadmap sentence, and the first mechanism section: ```mdx -**Tiered Cache** is a Cache feature that adds a cache layer between Azion's distributed infrastructure and the origin servers. With Tiered Cache enabled for the application, content stays cached for longer periods and the origin receives fewer requests. Tiered Cache is designed for objects that can remain in cache for a long period of time. Tiered Cache is available on request: activation goes through the Sales team. +**Tiered Cache** is a Feature of Cache that adds a cache layer between Azion's distributed infrastructure and the origin servers. With Tiered Cache enabled for the application, content stays cached for longer periods and the origin receives fewer requests. Tiered Cache is designed for objects that can remain in cache for a long period of time. Tiered Cache is available on request: activation goes through the Sales team. Its behavior depends on five mechanisms: the cache layers, the second-layer region, the TTL requirements, the Bypass Cache limitation, and the purge order. 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 611a460270..ce84a27e35 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 @@ -36,11 +36,11 @@ Descriptive: 25 words per sentence, active voice, passive only when the actor is **Required components** -- **Definition block**, in three parts. First the Platform Resource: `**** s .` That sentence names the resource and stands on its own: it 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. +- **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 `Product` on the Overview of a nested Product, 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 specimen**: where the Platform Resource has a code artifact, a configuration object, or a request, one complete, minimal example of it, in full, within the first screen. 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, then a numbered walk of at most six items. Open with what the reader would otherwise assume wrong. -- **The resources**: only on a Platform Resource that hosts Products. For each Product, say what it does on this resource and when the reader turns it on, in one or two sentences, then point to where the reader goes to use it. This is what the reader needs to decide whether to open the Product, never its feature list. +- **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 resources**: only on a Platform Resource that hosts Products. For each Product, 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 Product that…`. Then point to where the reader goes to use it. This is what the reader needs to decide whether to open the Product, 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. - **Closing**: `## Next steps`, a `DocCardGroup` indexed by what the reader wants to do: each card names the destination, and its copy is the intent (`Run your first one now.`). @@ -56,7 +56,7 @@ import DocButton from '~/components/webkit/DocButton.vue' import DocCardGroup from '@aziontech/webkit/doc-card-group' import DocCard from '@aziontech/webkit/doc-card' -**** s . +**** is a that s . Use to , , or . @@ -76,7 +76,7 @@ Use to , , or . ## - + @@ -103,7 +103,7 @@ Use to , , or . - **Never instruct.** No numbered steps, no procedures, no click-throughs. The specimen is not a walkthrough: it is shown once, complete, with nothing for the reader to do. An overview that instructs is a [quickstart page](/en/documentation/style-guide/content/quickstart/) filed wrong. - **No quality adjectives.** Say what the Platform Resource does and where it stops. - **The title is the Platform Resource name, a noun.** Not "documentation", not a gerund. -- **Put the Platform Resource before the concept.** The first sentence says what the Platform Resource does on Azion; the concept sentences follow it. Cover the Platform Resource name in the concept sentences: what remains must be true of any vendor's version of the thing. +- **Put the Platform Resource before the concept.** The first sentence states the class of the Platform Resource and what it does on Azion; the concept sentences follow it. Cover the Platform Resource name in the concept sentences: what remains must be true of any vendor's version of the thing. - **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, what am I writing, how does it get called, 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". - **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`. @@ -113,10 +113,10 @@ Use to , , or . ## Examples -This excerpt of the **Functions** overview shows the definition block in its three parts, then the specimen. The first sentence names the Platform Resource and 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, then the specimen. 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: ```mdx -**Functions** 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. +**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. ## Function structure 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 589a5587f7..76162793a9 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 @@ -69,7 +69,7 @@ Five rules cover most of the work on a Brazilian Portuguese page: - Do not translate generic technical terms: `data center`, `serverless`, `template`, `compliance`, `on-premise`. 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**. -- Apply the substitutions: `aplicação`, not `aplicativo`; `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`. +- Apply the substitutions: `application`, not `aplicação` or `aplicativo`, and every other instance name kept in US English; `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`. - 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/writing/terminology.mdx b/apps/docs/src/content/docs/en/pages/style-guide/writing/terminology.mdx index 501a463c06..46f3f7c86a 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 @@ -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. +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 at the root of a section 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. A page writes Product only as the class of a Product nested in a Platform Resource, 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. @@ -66,11 +66,33 @@ Azion Console, the API, the CLI, the Terraform Provider, and Copilot are also Pl - Correct: `Configure a firewall to protect the application.` - Correct: the sidebar row that opens WAF inside Firewall reads `WAF`, never `Firewall WAF` or `Web Application Firewall`, because a label never repeats its parent. +## State the class of an Azion element + +The sentence that defines an Azion element states its class: Platform Resource, Product, or Feature. `**Functions** is a Platform Resource that runs JavaScript code on Azion's distributed infrastructure.` A Feature carries its scope: `Tiered Cache is a Feature of Cache that…`. + +The class follows the documentation's nomenclature, not the naming catalog's list of Products: + +| The element | Its class on a page | Examples | +| --- | --- | --- | +| The root of a documentation section | Platform Resource, even when the catalog also lists it as a Product | Applications, Firewall, Functions, Object Storage, Workloads | +| Nested in a Platform Resource, and listed in the catalog as a Product | Product | WAF, Network Shield, Cache, Application Accelerator, Image Processor | +| Nested in a Platform Resource, and listed in the catalog as a Platform Resource | Platform Resource | Certificate Manager, Custom Pages, DDoS Protection | +| A functionality of the Platform or of a Platform Resource, in neither list | Feature, with its scope | Tiered Cache, custom firewall rules, DNSSEC | + +- **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. +- **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`, `produto`, and `feature`: `**Functions** é um recurso da plataforma que executa código JavaScript na infraestrutura distribuída da Azion.` + +- Correct: `**Applications** is a Platform Resource that runs a reverse proxy on Azion's distributed infrastructure.` +- Incorrect: `Applications is a product.` The class is wrong. +- Incorrect: `Functions is a serverless product.` A market category replaces the class. + ## Classify what lives inside a resource The words *module* and *add-on* are retired. What a page used to call a module is a Product enabled on a resource, such as Application Accelerator, Image Processor, WAF, or Network Shield. It can also be a feature of a resource, such as Tiered Cache, or a function instantiated on an application or a firewall. The retirement covers the classification of an Azion offering, nothing else. -- Correct: `Web Application Firewall (WAF) inspects the requests that reach a firewall. Apply a WAF rule set to the firewall.` +- Correct: `Web Application Firewall (WAF) is a Product that inspects the requests that reach a firewall. Apply a WAF rule set to the firewall.` - Incorrect: `Firewall is a product that includes WAF.` - Incorrect: `WAF is a Firewall module.` @@ -78,7 +100,7 @@ The words *module* and *add-on* are retired. What a page used to call a module i ## Give a plural-form name a singular verb -A Platform Resource name names one thing, whatever its form. Applications, Functions, and Connectors each take a singular verb: `Applications caches content`, `Functions runs your code` — never `Applications cache`. Brazilian Portuguese agrees the same way: `Functions executa suas funções`, never `executam`. +A Platform Resource name names one thing, whatever its form. Applications, Functions, and Connectors each take a singular verb: `Applications caches content`, `Functions runs your code` — never `Applications cache`. Brazilian Portuguese agrees the same way: `Functions executa suas functions`, never `executam`. ## Lowercase the thing the customer builds @@ -90,6 +112,10 @@ A Platform Resource name is capitalized. The thing a customer creates with them The distinction keeps the type name meaningful. A page that capitalizes both leaves the reader unable to tell the type from the instance. +Tie the instance to its Platform Resource where it first appears. A page that moves from the Platform Resource to the thing the reader creates says so once, with a class noun, and then uses the lowercase instance alone. Without that sentence, *application* also reads as the customer's own app, the one on the origin. + +- Correct: `An application is the object you create in Applications.` + ## Keep historical names in historical documents Changelogs, release notes, and dated agreements record what was true on the day of publication. These documents keep the names they shipped with. A Terms of Service from 2020 keeps the names that were correct in 2020. @@ -98,7 +124,7 @@ Do not rename an offering in a historical document. An updated name rewrites the ## Leave these terms in US English -The names of the Platform, Products, and Platform Resources are never translated. The thing the customer creates with them is translated: `Functions executa suas funções`. +The names of the Platform, Products, and Platform Resources are never translated. In Brazilian Portuguese, the instance the customer creates with a Platform Resource also keeps its US English name, in lowercase. That covers every instance whose name is the singular of its Platform Resource's name, such as an application, a function, a workload, a connector, or a firewall, and two objects with no Platform Resource of that name, the deployment and the bucket: `Functions executa suas functions`. Application and function take the feminine article, and the others the masculine: `a application`, `o workload`. A generic noun, such as rule, instance, certificate, or zone, is translated: `Crie uma regra na application`. These terms are generic technical vocabulary, not Platform Resource names. They stay in US English in both languages: @@ -111,3 +137,5 @@ The strings `edge` and `edge computing` also stay untranslated where they alread ## Name the infrastructure The platform runs on Azion's distributed infrastructure, never "on the global network". The physical site is a `data center`, never an edge location or a PoP. The unit of infrastructure inside a data center has no official name: write `the infrastructure in the data center`, never `node` or `edge node`. The network itself appears only as the Platform Resource **Our Network**. + +Name the data center that serves the request, not a distance: `from the data center nearest to your user`, never `close to your users` or `near your users`. The nearest data center is chosen by latency, network conditions, and load, so never write `geographically closest`. 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..c696dd6512 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 @@ -90,15 +90,15 @@ Cada objeto tem exatamente um campo de origem e exatamente um campo de destino: ### Como um redirect entra no ar -Cada arquivo de redirect é a lista de argumentos de uma instância da função Massive Redirect na aplicação da Azion que serve o site. O `pnpm --filter docs redirects:publish` valida os quatro arquivos, confere cada instância de destino e grava nas instâncias os arquivos que mudaram. A flag `--dry-run` informa o que mudaria e não grava nada. Os dois modos leem as instâncias publicadas, então os dois precisam das variáveis de ambiente `AZION_TOKEN` e `AZION_APPLICATION_ID`. +Cada arquivo de redirect é a lista de argumentos de uma instância da function Massive Redirect na application da Azion que serve o site. O `pnpm --filter docs redirects:publish` valida os quatro arquivos, confere cada instância de destino e grava nas instâncias os arquivos que mudaram. A flag `--dry-run` informa o que mudaria e não grava nada. Os dois modos leem as instâncias publicadas, então os dois precisam das variáveis de ambiente `AZION_TOKEN` e `AZION_APPLICATION_ID`. O workflow de deploy de produção roda a etapa de publicação depois de cada deploy de produção. Um merge na `main` sozinho não publica um redirect: o redirect entra no ar com o próximo deploy de produção. ### Quando um arquivo enche -Uma instância de função aceita no máximo 300 KB de argumentos, e a etapa de publicação rejeita um arquivo acima desse tamanho. Quando um arquivo se aproximar do limite, comece o próximo arquivo numerado, como `en/02.json`. Os arquivos não são ligados às instâncias de forma automática, então um arquivo novo é uma mudança de plataforma em três partes: +Uma instância de function aceita no máximo 300 KB de argumentos, e a etapa de publicação rejeita um arquivo acima desse tamanho. Quando um arquivo se aproximar do limite, comece o próximo arquivo numerado, como `en/02.json`. Os arquivos não são ligados às instâncias de forma automática, então um arquivo novo é uma mudança de plataforma em três partes: -1. Crie uma instância da função Massive Redirect na aplicação da Azion. +1. Crie uma instância da function Massive Redirect na application da Azion. 2. Carregue o arquivo em `apps/docs/redirects/index.js`. 3. Adicione o arquivo como destino em `apps/docs/cicd/massive-redirects/update-function-instances.mjs`, com o ID e o nome da instância. 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 adf6a4fd69..858b4cedc5 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 @@ -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 (`["application"]`), 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 @@ -219,7 +219,7 @@ import DocCardGroup from '@aziontech/webkit/doc-card-group' import DocCard from '@aziontech/webkit/doc-card' - + Firewall, WAF e proteção contra DDoS. ``` @@ -276,7 +276,7 @@ Um bloco de texto literal que o leitor entrega a um agente, em fonte mono e com ```mdx import DocPrompt from '@aziontech/webkit/doc-prompt' -Crie uma aplicação com cache habilitado e faça o deploy. +Crie uma application com cache habilitado e faça o deploy. ``` - `client:visible` é obrigatório: o botão de copiar e o de expandir precisam dele. 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 9ccc67ef18..fe59c6ba89 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 @@ -100,7 +100,7 @@ flowchart TD - **O diagrama nunca fica sozinho.** O fluxo de dados numerado carrega o significado, e ele permanece mesmo quando o diagrama é renderizado. - **Rotule cada elemento e cada seta com palavras**, e nunca dependa apenas de cor para carregar uma distinção. - **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. +- **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 application trata volta pela application, que a entrega. Uma resposta que o firewall dá vai direto ao cliente, porque a application 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. - **Nomeie cada componente e diga por que ele está ali.** Uma lista de nomes de recurso da plataforma é uma lista de peças. @@ -115,7 +115,7 @@ flowchart TD Este trecho mostra a abertura, a seção do diagrama e o fluxo de dados da página *Site estático orientado por Git*. O catálogo registra essa arquitetura de referência sob o caso de uso *Criar e operar sites de marketing*, que tem página publicada, então o caso de uso recebe o link: ````mdx -Um site estático cujas páginas e conteúdo vivem em um repositório Git. O Azion GitHub App constrói o site a cada push e envia o resultado para o Object Storage. Uma aplicação entrega esse resultado pelo Cache, e um build anterior pode ser reimplantado para reverter. Este design implementa o caso de uso [Criar e operar sites de marketing](/pt-br/documentacao/casos-de-uso/construir-e-executar-aplicacoes/criar-e-operar-sites-de-marketing/). +Um site estático cujas páginas e conteúdo vivem em um repositório Git. O Azion GitHub App constrói o site a cada push e envia o resultado para o Object Storage. Uma application entrega esse resultado pelo Cache, e um build anterior pode ser reimplantado para reverter. Este design implementa o caso de uso [Criar e operar sites de marketing](/pt-br/documentacao/casos-de-uso/construir-e-executar-aplicacoes/criar-e-operar-sites-de-marketing/). ## Diagrama de arquitetura @@ -125,7 +125,7 @@ Setas contínuas levam a requisição, setas pontilhadas levam a resposta, e set %%{init: {"layout": "elk", "themeVariables": {"fontSize": "13px"}, "flowchart": {"nodeSpacing": 24, "rankSpacing": 36, "padding": 8, "wrappingWidth": 150, "useMaxWidth": true}, "sequence": {"width": 120, "actorMargin": 30, "useMaxWidth": true}}}%% flowchart TD Client(["Cliente"]) - App["aplicação"] + App["application"] Cache["Cache"] Repo[["Repositório Git"]] GH["Azion GitHub App"] @@ -146,9 +146,9 @@ O conteúdo percorre o design nesta ordem: 1. Um push no repositório aciona o Azion GitHub App, que constrói o site. 2. O GitHub App envia o resultado do build para o bucket do Object Storage. -3. Um cliente envia uma requisição HTTP ou HTTPS ao domínio da aplicação que entrega o bucket. +3. Um cliente envia uma requisição HTTP ou HTTPS ao domínio da application que entrega o bucket. 4. No data center, o Cache responde à requisição com a sua cópia do arquivo quando a tem. -5. Em um cache miss, a aplicação lê o arquivo no bucket, e o Cache o guarda para a próxima requisição. +5. Em um cache miss, a application lê o arquivo no bucket, e o Cache o guarda para a próxima requisição. O fluxo de publicação só se move em um push, e os dois fluxos só se encontram no bucket. ```` 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..09aede9d8b 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 @@ -182,10 +182,10 @@ flowchart TD - **Explique o que é específico deste caso de uso. Os guias trazem o como.** As razões pelas quais o cenário muda uma configuração ficam na página. Os valores e o procedimento que os aplica ficam no guia, que nomeia este caso de uso. - **Limite a seção de design a quatro partes.** Uma parte atendida pelos padrões de um guia nunca conta: o guia dela é apontado na tabela de requisitos. Mais de quatro partes que precisam de subseção própria significa que a entrada é larga demais para uma página. Reduza a configuração à arquitetura de referência que a página constrói e informe a largura ao catálogo. Nunca aumente o limite, e nunca invente um segundo caso de uso. - **Faça o diagrama em `mermaid`.** O diagrama é texto, então um agente lendo a versão em Markdown recebe o design, não uma referência de imagem. O fluxo de dados numerado continua carregando o significado: o diagrama nunca fica sozinho. -- **Desenhe a requisição e o caminho de volta.** No flowchart da arquitetura de referência, 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 (`==>`). 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 nó só quando esse nó 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 nó que leu, com o rótulo do que ele devolve. A legenda acima do diagrama diz o que cada estilo de seta leva. +- **Desenhe a requisição e o caminho de volta.** No flowchart da arquitetura de referência, 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 (`==>`). 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 nó só quando esse nó age sobre a resposta, como o Cache que armazena uma cópia. Uma resposta que a application trata volta pela application, que a entrega. Uma resposta que o firewall dá vai direto ao cliente, porque a application nunca recebe essa requisição. Uma leitura também tem caminho de volta: uma seta pontilhada do armazenamento de dados até o nó 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 do diagrama da arquitetura de referência 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. Um diagrama em `## Como o design funciona` segue a lista que vem abaixo dele. - **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. O que o design mostra e nenhuma etapa diz, como qual parte fica no fluxo de falha, vem depois da lista. -- **Dê uma forma a cada papel.** O cliente é um estádio (`(["Visitante"])`). 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 (`[["plataforma de e-commerce"]]`). Forma e estilo de linha carregam toda distinção, nunca a cor. +- **Dê uma forma a cada papel.** O cliente é um estádio (`(["Visitante"])`). Tudo o que está na Azion, um produto ou um recurso da plataforma, é um retângulo (`["application"]`). Um armazenamento de dados é um cilindro (`[("KV Store")]`), e um sistema fora da Azion é uma sub-rotina (`[["plataforma de e-commerce"]]`). Forma e estilo de linha carregam toda distinção, nunca a cor. - **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. - **Abra todo diagrama com a linha `init` compartilhada**, como o template 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 cliente não aparece no topo, adicione um objeto `elk` logo depois de `"layout": "elk",` com 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`. - **Meça, não verifique.** A checagem única de que uma configuração está correta fica nas seções de confirmação dos guias. A página nomeia os sinais contínuos que mostram que o design continua funcionando. 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 34f08fc434..81b1d0c8e7 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 @@ -108,7 +108,7 @@ ele se comporta e o que ele custa.> Este exemplo mostra a abertura, a frase-roteiro e a primeira seção de mecanismo de uma página de conceito sobre o Tiered Cache: ```mdx -O **Tiered Cache** é uma feature do Cache que adiciona uma camada de cache entre a infraestrutura distribuída da Azion e os servidores de origem. Com o Tiered Cache ativado na aplicação, o conteúdo fica em cache por mais tempo e a origem recebe menos requisições. O Tiered Cache foi projetado para objetos que podem permanecer em cache por um longo período. O Tiered Cache está disponível sob solicitação: a ativação passa pelo time de vendas. +O **Tiered Cache** é uma feature do Cache que adiciona uma camada de cache entre a infraestrutura distribuída da Azion e os servidores de origem. Com o Tiered Cache ativado na application, o conteúdo fica em cache por mais tempo e a origem recebe menos requisições. O Tiered Cache foi projetado para objetos que podem permanecer em cache por um longo período. O Tiered Cache está disponível sob solicitação: a ativação passa pelo time de vendas. O comportamento dele depende de cinco mecanismos: as camadas de cache, a região da segunda camada, os requisitos de TTL, a limitação do Bypass Cache e a ordem do purge. 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 55285a9306..cb2e1a6757 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 @@ -64,7 +64,7 @@ Alguns tipos comuns em outras documentações estão ausentes de propósito, por Tutoriais e guias how-to contêm passos. Eles servem leitores opostos, e essa é a distinção que mais importa. -O leitor de tutorial ainda não sabe o que quer. Ele aprende, e você ensina. Você escolhe o objetivo, garante o resultado e mantém as decisões longe do leitor. "Faça o deploy da sua primeira aplicação" é um tutorial: o leitor não tem uma aplicação em mente, e qualquer aplicação serve. +O leitor de tutorial ainda não sabe o que quer. Ele aprende, e você ensina. Você escolhe o objetivo, garante o resultado e mantém as decisões longe do leitor. "Faça o deploy da sua primeira application" é um tutorial: o leitor não tem uma application em mente, e qualquer application serve. O leitor de how-to já sabe o que quer. Ele chegou com um problema. Você remove obstáculos; você não ensina. "Configure políticas de cache" é um how-to: o leitor tem um problema de cache e quer o problema resolvido. 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..cd0c5bffb8 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 @@ -40,7 +40,7 @@ Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo **Componentes obrigatórios** -- **Abertura pelo problema**: uma ou duas frases declaram o problema, antes de qualquer nome de recurso da plataforma. Os recursos da plataforma, e os produtos configurados neles, entram depois do problema, pelo papel: "Você configura o cache na aplicação e a filtragem de requisições no firewall." +- **Abertura pelo problema**: uma ou duas frases declaram o problema, antes de qualquer nome de recurso da plataforma. Os recursos da plataforma, e os produtos configurados neles, entram depois do problema, pelo papel: "Você configura o cache na application e a filtragem de requisições no firewall." - **Pré-requisitos**: uma seção `## Pré-requisitos`, em lista; cada item é um link ou um comando de uma linha. Um único pré-requisito é uma frase, não uma lista. - **Etapas**: um `##` por etapa do fluxo, nunca por recurso da plataforma, cada um com um título imperativo que nomeia a etapa. Cada etapa nomeia seu recurso da plataforma na entrada, contém um procedimento comum e se sustenta sozinha. - **Frase de resultado**: todo procedimento termina declarando o que o leitor agora tem ou vê. @@ -97,7 +97,7 @@ Separe as seções principais da página com uma régua `---`, e nunca coloque u ## Regras - **Nomeie o objetivo, não os recursos da plataforma.** O título declara o objetivo em linguagem simples, sem nomes de recurso da plataforma: `Sirva um site com conteúdo em cache e um checkout protegido`. O leitor busca pelo resultado. -- **Declare o problema primeiro.** Uma ou duas frases, depois os recursos da plataforma, e os produtos configurados neles, pelo papel: "Você configura o cache na aplicação e a filtragem de requisições no firewall." +- **Declare o problema primeiro.** Uma ou duas frases, depois os recursos da plataforma, e os produtos configurados neles, pelo papel: "Você configura o cache na application e a filtragem de requisições no firewall." - **Ordene pelo fluxo, nunca pelo catálogo de recursos da plataforma.** Uma página organizada um recurso da plataforma por vez é um pacote de guias how-to com um só título. - **Nomeie o recurso da plataforma em cada etapa.** Um nome de interface sem qualificação fica ambíguo quando a página cruza recursos da plataforma. - **Continue sendo um how-to.** Os recursos da plataforma são a rota, não o assunto. Um parágrafo de contexto de recurso da plataforma pertence a uma página de conceito; aponte para ela. @@ -112,25 +112,25 @@ Separe as seções principais da página com uma régua `---`, e nunca coloque u O trecho a seguir mostra a abertura pelo problema, os pré-requisitos e a primeira etapa do fluxo: ```mdx -Cada rota de uma loja precisa de uma regra diferente. O catálogo pode responder do cache, o carrinho não, e o checkout precisa de um limite de taxa. Você configura o cache na aplicação e a filtragem de requisições no firewall. +Cada rota de uma loja precisa de uma regra diferente. O catálogo pode responder do cache, o carrinho não, e o checkout precisa de um limite de taxa. Você configura o cache na application e a filtragem de requisições no firewall. ## Pré-requisitos -- Uma aplicação que serve a loja +- Uma application que serve a loja - Um firewall ## Ative o Application Accelerator -O behavior **Bypass Cache** exige o **Application Accelerator** ativado na aplicação. +O behavior **Bypass Cache** exige o **Application Accelerator** ativado na application. Para ativá-lo: -1. Acesse o [Azion Console](https://console.azion.com/) > **Applications** > **sua aplicação**. +1. Acesse o [Azion Console](https://console.azion.com/) > **Applications** > **sua application**. 2. Na aba **Main Settings**, vá até a seção **Modules**. 3. Ative a chave **Application Accelerator**. 4. Selecione **Save**. -O Application Accelerator está ativado na aplicação. +O Application Accelerator está ativado na application. ``` ## 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 0bd767833f..6015a0f51b 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 @@ -39,7 +39,7 @@ Uma página de quickstart segue o esqueleto do tutorial, com uma diferença: os - **Abertura**: `Este guia orienta você por .` seguido de uma lista curta com marcadores do que o leitor terá feito. Enquadre o resultado como um primeiro: "seu primeiro bucket", "seu primeiro deploy". - **Cadeia de objetos**: depois da abertura, nomeie cada objeto que o leitor cria e a que cada um precisa ser vinculado, em ordem. Uma lista curta, antes dos pré-requisitos. - **Pré-requisitos**: uma seção `## Pré-requisitos` com itens em marcadores. Cada item é um link, um comando de uma linha ou uma frase nominal que nomeia o requisito. Um único pré-requisito é uma frase, não uma lista. -- **Etapas**: títulos de etapa sem número, `## `, na ordem de construção, terminando em uma etapa que ativa ou verifica. `(Opcional)` abre o título de uma etapa opcional: `## (Opcional) Altere o modelo que a função chama`. Cada etapa contém um procedimento e termina com sua frase de resultado. Quando a etapa carrega tabs de interface, cada painel abre com um título que nomeia a interface, e o procedimento e a frase de resultado ficam dentro dele. +- **Etapas**: títulos de etapa sem número, `## `, na ordem de construção, terminando em uma etapa que ativa ou verifica. `(Opcional)` abre o título de uma etapa opcional: `## (Opcional) Altere o modelo que a function chama`. Cada etapa contém um procedimento e termina com sua frase de resultado. Quando a etapa carrega tabs de interface, cada painel abre com um título que nomeia a interface, e o procedimento e a frase de resultado ficam dentro dele. - **Próximos passos**: um fechamento `## Próximos passos`, um `DocCardGroup` com um card por destino: o título, o link e uma frase sobre por que o leitor seguiria o link. **Componentes opcionais** 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 e82fca001d..e3d5be9225 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 @@ -36,11 +36,11 @@ Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é **Componentes obrigatórios** -- **Bloco de definição**, em três partes. Primeiro o recurso da plataforma: `**** .` Essa frase nomeia o recurso e se sustenta sozinha: ela 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. +- **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` na visão geral de uma seção e `produto` na visão geral de um produto 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 `. - **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, na primeira tela. 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`, seguido de um percurso numerado com no máximo seis itens. Abra com o que o leitor presumiria errado. -- **Os recursos**: somente em um recurso da plataforma que hospeda produtos. Para cada produto, diga o que ele faz neste recurso e quando o leitor o ativa, em uma ou duas frases, e depois aponte para onde o leitor vai para usá-lo. É o que o leitor precisa para decidir se abre o produto, nunca a lista de features. +- **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 instância de function que uma regra invoca.` +- **Os recursos**: somente em um recurso da plataforma que hospeda produtos. Para cada produto, 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 produto que…`. Depois aponte para onde o leitor vai para usá-lo. É o que o leitor precisa para decidir se abre o produto, 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. - **Fechamento**: `## Próximos passos`, um `DocCardGroup` indexado pelo que o leitor quer fazer: cada card nomeia o destino, e seu texto é a intenção (`Rode o primeiro agora.`). @@ -56,7 +56,7 @@ import DocButton from '~/components/webkit/DocButton.vue' import DocCardGroup from '@aziontech/webkit/doc-card-group' import DocCard from '@aziontech/webkit/doc-card' -**** . +**** é um que . Use para , ou . @@ -76,7 +76,7 @@ Use para , ou . ## - + @@ -103,20 +103,20 @@ Use para , ou . - **Nunca instrua.** Sem passos numerados, sem procedimentos, sem sequências de cliques. A amostra não é um passo a passo: ela aparece uma vez, completa, sem nada para o leitor fazer. Uma visão geral que instrui é uma página de [quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) arquivada no lugar errado. - **Sem adjetivos de qualidade.** Diga o que o recurso da plataforma faz e onde para. - **O título é o nome do recurso da plataforma, um substantivo.** Não "documentação", não um gerúndio. -- **Coloque o recurso da plataforma antes do conceito.** A primeira frase diz o que o recurso da plataforma faz na Azion; as frases de conceito vêm depois. Cubra o nome do recurso da plataforma nas frases de conceito: o que sobra precisa valer para a versão de qualquer fornecedor. +- **Coloque o recurso da plataforma antes do conceito.** A primeira frase declara a classe do recurso da plataforma e o que ele faz na Azion; as frases de conceito vêm depois. Cubra o nome do recurso da plataforma nas frases de conceito: o que sobra precisa valer para a versão de qualquer fornecedor. - **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, o que eu escrevo, como isso é chamado, 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". -- **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`. +- **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 function`, não `Como é uma function`. - **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. - **Nunca encurte a amostra nem tire o diagrama para deixar a página mais curta.** Eles são as duas coisas que o leitor veio buscar. Quando uma página fica longa, o excesso está nas seções de capacidade; comprima-as no bloco de fronteiras. ## 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 depois a amostra. A primeira frase nomeia o recurso da plataforma e 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 depois a amostra. 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 function para um leitor que nunca usou uma; a frase de usos fecha o bloco; a amostra mostra o artefato em vez de descrevê-lo: ```mdx -**Functions** 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. +**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. ## Function structure 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 d27956cbea..c32ae8942d 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 @@ -69,7 +69,7 @@ Cinco regras cobrem a maior parte do trabalho em uma página em português do Br - Não traduza termos técnicos genéricos: `data center`, `serverless`, `template`, `compliance`, `on-premise`. As strings `edge` e `edge computing` permanecem sem tradução onde já aparecem, mas textos novos não as introduzem. - Não traduza nomes de recursos da plataforma nem outros nomes da Azion: **Applications**, **Functions**, **Firewall**, **Azion Platform**, **Azion Marketplace**. -- Aplique as substituições: `aplicação`, não `aplicativo`; `rede distribuída`, não `borda`, ao traduzir texto existente; `performance`, não `desempenho`. Texto novo em português do Brasil que nomeia onde a plataforma roda escreve `infraestrutura distribuída`. +- Aplique as substituições: `application`, não `aplicação` nem `aplicativo`, e todo outro nome de instância mantido em inglês dos EUA; `rede distribuída`, não `borda`, ao traduzir texto existente; `performance`, não `desempenho`. Texto novo em português do Brasil que nomeia onde a plataforma roda escreve `infraestrutura distribuída`. - Escreva títulos com maiúscula só na primeira palavra e nos nomes próprios. - Localize os rótulos dos asides: `:::note[nota]`, `:::tip[dica]`, `:::caution[Atenção]`, `:::danger[perigo]`. A caixa segue o uso do repositório: `nota`, `dica` e `perigo` em minúscula, `Atenção` com maiúscula. Um rótulo em inglês dos EUA em uma página em português do Brasil é um defeito visível. 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 bbae03d9f8..8d29e03b32 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 @@ -40,8 +40,8 @@ Escreva com o imperativo, o presente simples, o passado simples e o futuro simpl Em inglês dos EUA, um termo em -ing precisa ser um substantivo ou parte de um, como em `caching` ou `request logging`. Não use um termo em -ing como verbo nem como oração final. Em português do Brasil, o mesmo defeito aparece como oração final no gerúndio, que esconde quem age e quando a ação acontece. -- Antes: `A função valida o token, retornando um erro quando a assinatura falha.` -- Depois: `A função valida o token. Quando a assinatura falha, a função retorna um erro.` +- Antes: `A function valida o token, retornando um erro quando a assinatura falha.` +- Depois: `A function valida o token. Quando a assinatura falha, a function retorna um erro.` A mesma lógica vale para títulos de tarefa, que começam com um verbo no imperativo, não com gerúndio. As regras completas estão em [Títulos](/pt-br/documentacao/guia-de-estilo/formatacao/titulos/). @@ -74,13 +74,13 @@ Formate três ou mais passos, condições ou alternativas como uma lista numerad Antes: -`Salve o arquivo, depois execute o build e depois faça o deploy da aplicação.` +`Salve o arquivo, depois execute o build e depois faça o deploy da application.` Depois: 1. Salve o arquivo. 2. Execute o build. -3. Faça o deploy da aplicação. +3. Faça o deploy da application. ## Use a mesma palavra para a mesma ação diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/procedimentos.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/procedimentos.mdx index ecbf091741..a67ec0d8d2 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/procedimentos.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/procedimentos.mdx @@ -18,7 +18,7 @@ Procedimentos no Console começam com a string canônica: 1. Acesse [Azion Console](https://console.azion.com/) > ****. ``` -Preencha o recurso da plataforma: `> **Object Storage**`, `> **Firewall**`. Uma navegação mais profunda estende a cadeia: `> **Applications** > **sua aplicação**`. +Preencha o recurso da plataforma: `> **Object Storage**`, `> **Firewall**`. Uma navegação mais profunda estende a cadeia: `> **Applications** > **sua application**`. Um procedimento de um único comando não é uma lista numerada. Escreva uma frase de introdução terminada em dois-pontos e depois o comando: @@ -66,7 +66,7 @@ A condição vem antes da ação: `Se a lista estiver vazia, selecione **Add**.` Imediatamente antes da lista numerada, uma frase declara o objetivo e termina em dois-pontos: ``` -Para fazer o deploy do conjunto de regras da sua aplicação: +Para fazer o deploy do conjunto de regras da sua application: ``` Use dois-pontos quando a frase precede os passos imediatamente. Use ponto final quando algo fica entre eles, como um aside. Nunca escreva uma frase parcial que os passos completam. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/terminologia.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/terminologia.mdx index aaa6466acf..d43e602dc5 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/terminologia.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/escrita/terminologia.mdx @@ -52,25 +52,47 @@ A Azion descreve o que oferece com quatro termos: plataforma, produto, recurso d | --- | --- | --- | | Plataforma | O que é a experiência integrada da Azion? | A infraestrutura distribuída da Azion, sua tecnologia integrada e as interfaces para construir, proteger e escalar workloads, como o Console, a API e a CLI | | Produto | Que oferta a Azion leva ao mercado? | Uma oferta de mercado formada por um ou mais recursos da plataforma e features que resolve um problema do cliente, como WAF ou Object Storage | -| Recurso da plataforma | O que o leitor cria ou gerencia? | Uma entidade identificável que o cliente cria, configura, opera ou gerencia, e que o Console, a API, a CLI ou a documentação podem referenciar, como uma aplicação, um firewall, uma função ou um bucket | +| Recurso da plataforma | O que o leitor cria ou gerencia? | Uma entidade identificável que o cliente cria, configura, opera ou gerencia, e que o Console, a API, a CLI ou a documentação podem referenciar, como uma application, um firewall, uma function ou um bucket | | Feature | O que o leitor pode fazer ou ativar? | Uma funcionalidade visível da plataforma ou de um recurso da plataforma, que um produto pode incluir, como regras personalizadas de firewall ou DNSSEC | -A documentação usa a nomenclatura de recurso da plataforma. Produto é um termo de go-to-market, usado principalmente em material de marketing e vendas, e a tabela o define para o leitor reconhecê-lo lá. Uma página de documentação chama cada seção pelo nome oficial e chama a oferta de recurso da plataforma, nunca de produto: ela nomeia o que o leitor cria ou gerencia, e liga um recurso da plataforma a outro com um verbo. +A documentação usa a nomenclatura de recurso da plataforma. Produto é um termo de go-to-market, usado principalmente em material de marketing e vendas, e a tabela o define para o leitor reconhecê-lo lá. Uma página de documentação chama cada seção pelo nome oficial e chama a oferta na raiz de uma seção de recurso da plataforma, nunca de produto: ela nomeia o que o leitor cria ou gerencia, e liga um recurso da plataforma a outro com um verbo. Uma página escreve produto só como a classe de um produto aninhado em um recurso da plataforma, conforme [Declare a classe de um elemento da Azion](#declare-a-classe-de-um-elemento-da-azion). Uma feature sempre tem escopo, então diga se ela vale para a plataforma ou para um recurso da plataforma. Um campo ou uma opção de um recurso é uma configuração, não uma feature. -**Applications**, **Firewall**, **Connectors**, **Workloads**, **Custom Pages** e **Certificate Manager** são exemplos de tipos de recurso da plataforma; o catálogo de nomes tem a lista completa. A coisa que o leitor cria é uma instância, em minúscula: uma aplicação, um firewall, um connector. +**Applications**, **Firewall**, **Connectors**, **Workloads**, **Custom Pages** e **Certificate Manager** são exemplos de tipos de recurso da plataforma; o catálogo de nomes tem a lista completa. A coisa que o leitor cria é uma instância, em minúscula: uma application, um firewall, um connector. -Azion Console, a API, a CLI, o Terraform Provider e o Copilot também são recursos da plataforma. São eles que o leitor usa para chegar à plataforma, então uma página pode chamá-los de interfaces: `Crie a aplicação no Console ou com a API.` +Azion Console, a API, a CLI, o Terraform Provider e o Copilot também são recursos da plataforma. São eles que o leitor usa para chegar à plataforma, então uma página pode chamá-los de interfaces: `Crie a application no Console ou com a API.` -- Correto: `Configure um firewall para proteger a aplicação.` +- Correto: `Configure um firewall para proteger a application.` - Correto: a linha da sidebar que abre o WAF dentro de Firewall diz `WAF`, nunca `Firewall WAF` nem `Web Application Firewall`, porque um rótulo nunca repete o pai. +## Declare a classe de um elemento da Azion + +A frase que define um elemento da Azion declara a classe dele: recurso da plataforma, produto ou feature. `**Functions** é um recurso da plataforma que executa código JavaScript na infraestrutura distribuída da Azion.` Uma feature leva o escopo: `O Tiered Cache é uma feature do Cache que…`. + +A classe segue a nomenclatura da documentação, não a lista de produtos do catálogo de nomes: + +| O elemento | A classe dele em uma página | Exemplos | +| --- | --- | --- | +| A raiz de uma seção da documentação | Recurso da plataforma, mesmo quando o catálogo também o lista como produto | Applications, Firewall, Functions, Object Storage, Workloads | +| Aninhado em um recurso da plataforma e listado no catálogo como produto | Produto | WAF, Network Shield, Cache, Application Accelerator, Image Processor | +| Aninhado em um recurso da plataforma e listado no catálogo como recurso da plataforma | Recurso da plataforma | Certificate Manager, Custom Pages, DDoS Protection | +| Uma funcionalidade da plataforma ou de um recurso da plataforma, em nenhuma das listas | Feature, com o escopo | Tiered Cache, regras personalizadas de firewall, DNSSEC | + +- **Uma vez por página, na primeira definição do elemento.** É a primeira frase de uma visão geral, cada entrada da seção de recursos dela, a frase de uma página de conceito que apresenta o elemento, uma linha de glossário que o define e a primeira frase de qualquer outra página que diz o que o elemento é. +- **Uma menção de passagem não leva classe.** `Crie um firewall` e `Abra a application` ficam como estão. Uma entrada de changelog descreve uma mudança, não o elemento, e mantém a abertura que [Páginas de changelog](/pt-br/documentacao/guia-de-estilo/conteudo/changelog/) define. +- **A classe não substitui o conceito.** A classe diz o que o elemento é dentro da Azion. As frases de conceito depois dela continuam dizendo o que é a classe da coisa em qualquer fornecedor: um proxy reverso é um servidor na frente das suas origens. +- **Em inglês dos EUA**, as classes são `Platform Resource`, `Product` e `Feature`: `**Functions** is a Platform Resource that runs JavaScript code on Azion's distributed infrastructure.` + +- Correto: `**Applications** é um recurso da plataforma que executa um proxy reverso na infraestrutura distribuída da Azion.` +- Incorreto: `Applications é um produto.` A classe está errada. +- Incorreto: `Functions é um produto serverless.` Uma categoria de mercado substitui a classe. + ## Classifique o que vive dentro de um recurso -As palavras *módulo* e *add-on* estão aposentadas. O que uma página chamava de módulo é um produto habilitado em um recurso, como Application Accelerator, Image Processor, WAF ou Network Shield. Também pode ser uma feature de um recurso, como o Tiered Cache, ou uma função instanciada em uma aplicação ou em um firewall. A aposentadoria cobre a classificação de uma oferta da Azion, e nada mais. +As palavras *módulo* e *add-on* estão aposentadas. O que uma página chamava de módulo é um produto habilitado em um recurso, como Application Accelerator, Image Processor, WAF ou Network Shield. Também pode ser uma feature de um recurso, como o Tiered Cache, ou uma function instanciada em uma application ou em um firewall. A aposentadoria cobre a classificação de uma oferta da Azion, e nada mais. -- Correto: `Web Application Firewall (WAF) inspeciona as requisições que chegam a um firewall. Aplique um conjunto de regras WAF ao firewall.` +- Correto: `Web Application Firewall (WAF) é um produto que inspeciona as requisições que chegam a um firewall. Aplique um conjunto de regras WAF ao firewall.` - Incorreto: `Firewall é um produto que inclui o WAF.` - Incorreto: `WAF é um módulo do Firewall.` @@ -84,12 +106,16 @@ Um nome de recurso da plataforma nomeia uma coisa só, qualquer que seja a forma O nome de um recurso da plataforma leva maiúscula. A coisa que o cliente cria com ele é um substantivo comum, e fica em minúscula. -- Correto: `Use **Applications** para construir suas próprias aplicações.` -- Correto: `**Functions** executa suas funções na infraestrutura distribuída da Azion.` +- Correto: `Use **Applications** para construir suas próprias applications.` +- Correto: `**Functions** executa suas functions na infraestrutura distribuída da Azion.` - Incorreto: `Faça o deploy da sua primeira Application.` A distinção mantém o nome do tipo com significado. Uma página que escreve os dois em maiúscula deixa o leitor sem saber o que é o tipo e o que é a instância. +Ligue a instância ao recurso da plataforma onde ela aparece pela primeira vez. Uma página que passa do recurso da plataforma para a coisa que o leitor cria diz isso uma vez, com um substantivo de classe, e depois usa só a instância em minúscula. Sem essa frase, *application* também se lê como o app do próprio cliente, o que está na origem. + +- Correto: `Uma application é o objeto que você cria em Applications.` + ## Mantenha nomes históricos em documentos históricos Changelogs, release notes e contratos datados registram o que era verdade no dia da publicação. Esses documentos mantêm os nomes da época da publicação. Uns Termos de Serviço de 2020 mantêm os nomes que eram corretos em 2020. @@ -98,7 +124,7 @@ Não renomeie uma oferta em um documento histórico. Um nome atualizado reescrev ## Deixe estes termos em inglês dos EUA -Os nomes da plataforma, dos produtos e dos recursos da plataforma nunca são traduzidos. A coisa que o cliente cria com eles é traduzida: `Functions executa suas funções`. +Os nomes da plataforma, dos produtos e dos recursos da plataforma nunca são traduzidos. Em português do Brasil, a instância que o cliente cria com um recurso da plataforma também mantém o nome em inglês dos EUA, em minúscula. Isso vale para toda instância cujo nome é o singular do nome do recurso, como uma application, uma function, um workload, um connector ou um firewall, e para dois objetos sem recurso desse nome, o deployment e o bucket: `Functions executa suas functions`. Application e function levam artigo feminino, e os outros, masculino: `a application`, `o workload`. Um substantivo genérico, como regra, instância, certificado ou zona, é traduzido: `Crie uma regra na application`. Estes termos são vocabulário técnico genérico, não nomes de recurso da plataforma. Eles ficam em inglês dos EUA nos dois idiomas: @@ -111,3 +137,5 @@ As strings `edge` e `edge computing` também ficam sem tradução onde já apare ## Nomeie a infraestrutura A plataforma roda na infraestrutura distribuída da Azion, nunca "na rede global". O local físico é um `data center`, nunca um edge location nem um PoP; `data center` fica em inglês, nunca "centro de dados". A unidade de infraestrutura dentro de um data center não tem nome oficial: escreva `a infraestrutura no data center`, nunca `nó` nem `edge node`. A rede em si aparece só como o recurso da plataforma **Our Network**. + +Nomeie o data center que atende a requisição, não uma distância: `do data center mais próximo ao seu usuário`, nunca `perto dos seus usuários` nem `próximo aos seus usuários`. O data center mais próximo é escolhido por latência, condições de rede e carga, então nunca escreva `geograficamente mais próximo`. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/pontuacao.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/pontuacao.mdx index 77a56aee80..3591999cd3 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/pontuacao.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/pontuacao.mdx @@ -91,7 +91,7 @@ Evite o ponto e vírgula. Duas orações unidas por ponto e vírgula são duas f | Regra | Exemplo | | --- | --- | -| Um espaço depois de ponto, interrogação ou dois-pontos | `Salve a regra. Faça o deploy da aplicação.` | +| Um espaço depois de ponto, interrogação ou dois-pontos | `Salve a regra. Faça o deploy da application.` | | Sem espaço ao redor da barra | `100 km/h` | | O sinal de porcentagem gruda no número | `100%` | | Escreva `e`, nunca `&` | `Regras e comportamentos` | diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/texto.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/texto.mdx index db53f86bdb..2afb571c40 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/texto.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/texto.mdx @@ -73,7 +73,7 @@ Links dentro de um parágrafo apontam para páginas da documentação. Links ext ## Aponte a primeira menção de outro elemento documentado -Quando a prosa nomeia um recurso da plataforma, um produto aninhado ou uma feature que tem página própria, a primeira menção na página aponta para essa página: `Configure um [firewall](/pt-br/documentacao/plataforma/firewall/) para proteger a aplicação.` As menções seguintes ficam em texto simples, ou em negrito onde a regra de nomes de produto pede. +Quando a prosa nomeia um recurso da plataforma, um produto aninhado ou uma feature que tem página própria, a primeira menção na página aponta para essa página: `Configure um [firewall](/pt-br/documentacao/plataforma/firewall/) para proteger a application.` As menções seguintes ficam em texto simples, ou em negrito onde a regra de nomes de produto pede. O link substitui o negrito nessa primeira menção, porque o texto dentro de um link nunca fica em negrito. Um leitor que encontra um nome desconhecido sempre tem a página dele a um clique. From d6de1d6de01a616c02852f967eab8af830d0fd67 Mon Sep 17 00:00:00 2001 From: Marcus Souza Date: Fri, 6 Nov 2026 11:55:28 -0300 Subject: [PATCH 3/5] docs(style-guide): add cohesion rules to Sentence structure Sentence structure gains the rules that keep a paragraph saying one thing, in en and pt-br: - Connect each sentence to the one before, and name a change of topic with its connective. - Let the first sentences of paragraphs and bullet lead-ins carry the section; a compressed bullet stays on its lead-in's topic. - Introduce one new term per sentence. - A restated list keeps its words, and an interface string follows the fact it implies. The checklist gains a line for each. --- .../writing/sentence-structure.mdx | 32 +++++++++++++++++-- .../escrita/estrutura-de-frases.mdx | 32 +++++++++++++++++-- 2 files changed, 60 insertions(+), 4 deletions(-) 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 ce281d7629..7e0311aa75 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 @@ -66,6 +66,29 @@ Write one topic per paragraph, in six sentences at most. Retrieval systems cut p - Before: one paragraph that defines the cache key and then describes purge behavior. - After: one paragraph for the cache key, and a second paragraph for purge behavior. +## Connect each sentence to the one before + +Each sentence continues the topic of the sentence before it: its subject is the subject of that sentence, or something that sentence introduced. When the topic moves on purpose, open the sentence with the word that names the move: `Because`, `If`, `When`, `Otherwise`, `Each`. A consequence names its cause in the same way, so the reader never has to supply the link. + +- Before: `**Applications** is a Platform Resource that runs a reverse proxy. Each application serves the workloads whose deployment names it. A reverse proxy is a server in front of your origins.` +- After: `**Applications** is a Platform Resource that runs a reverse proxy. A reverse proxy is a server in front of your origins. Each application serves the workloads whose deployment names it.` + +## Let the first sentences carry the section + +Read alone, the first sentence of each paragraph and the bold lead-in of each bullet carry the point of the section, in order. A reader who skims reads only those. A first sentence that is a caveat, a pointer, or a negation that never says what happens instead leaves that reader with nothing. + +In a compressed block of bullets, every sentence of a bullet stays on the topic of its lead-in. A fact on another topic opens its own bullet. + +- Before: `Creating an application serves nothing.` +- After: `Creating an application serves nothing on its own: an application handles only the requests of a workload whose deployment names it.` + +## Introduce one new term per sentence + +A sentence that coins two terms makes the reader learn both at once and keep them apart. Introduce one new term per sentence, and keep one name for each thing after that. + +- Before: `Image Processor builds a new image, the derived image, from the original image on your origin, the source image.` +- After: `Image Processor builds each image it delivers from an image on your origin, the source image. The image it delivers is the derived image.` + ## Use a vertical list for a sequence Format three or more steps, conditions, or alternatives as a numbered or bulleted list. A sequence inside one prose sentence forces the reader to parse the order and the actions at the same time. @@ -87,7 +110,9 @@ Pick one verb for one action and repeat it across the page. A rotation of synony - Before: `Verify that the build passed. Then check that the deploy passed.` - After: `Verify that the build passed. Then verify that the deploy passed.` -When a sentence describes a control in the Console, use the label that the Console shows. Do not improve on the vocabulary of the interface. +The rule extends to the items of a list. When a later sentence restates a list, it keeps the words of the first one: `add or remove a header`, then `add or filter headers`, reads as two different capabilities. + +When a sentence describes a control in the Console, use the label that the Console shows. Do not improve on the vocabulary of the interface. When an interface string implies a fact, state the fact first, then quote the string as its source. A quoted string alone leaves the reader to derive the rule. ASD-STE100 pairs its rules with an approved dictionary. Rules 1.5 and 1.12 of the standard let a project approve its own technical names and technical verbs. Azion uses that allowance: the approved vocabulary is in [Word choice](/en/documentation/style-guide/writing/word-choice/) and in [Documentation terminology](/en/documentation/style-guide/writing/terminology/). @@ -100,8 +125,11 @@ Confirm each point before the page ships: - Every noun cluster has at most three words, with a Platform Resource name counted as one word. - Every sentence keeps its subject, its verb, and its articles. - Every paragraph covers one topic in at most six sentences. +- Every sentence continues the topic of the one before, or opens with the word that names the move. +- The first sentences of the paragraphs and the lead-ins of the bullets, read alone, carry each section. +- Every sentence introduces at most one new term. - Every sequence of three or more items is a vertical list. -- Every action keeps the same verb across the page. +- Every action keeps the same verb across the page, and every restated list keeps its words. ## Sources 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 8d29e03b32..0ef1e909a6 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 @@ -68,6 +68,29 @@ Escreva um tópico por parágrafo, em no máximo seis frases. Sistemas de busca - Antes: um parágrafo que define a cache key e depois descreve o purge. - Depois: um parágrafo para a cache key e um segundo parágrafo para o purge. +## Ligue cada frase à anterior + +Cada frase continua o tópico da frase anterior: o sujeito dela é o sujeito daquela frase ou algo que aquela frase apresentou. Quando o tópico muda de propósito, abra a frase com a palavra que nomeia a mudança: `Porque`, `Se`, `Quando`, `Caso contrário`, `Cada`. Uma consequência nomeia a causa da mesma forma, para que o leitor nunca precise completar a ligação. + +- Antes: `**Applications** é um recurso da plataforma que executa um proxy reverso. Cada application atende os workloads cujo deployment a nomeia. Um proxy reverso é um servidor na frente das suas origens.` +- Depois: `**Applications** é um recurso da plataforma que executa um proxy reverso. Um proxy reverso é um servidor na frente das suas origens. Cada application atende os workloads cujo deployment a nomeia.` + +## Deixe as primeiras frases carregarem a seção + +Lidas sozinhas, a primeira frase de cada parágrafo e a introdução em negrito de cada bullet carregam o ponto da seção, em ordem. Um leitor que passa os olhos pela página lê só essas frases. Uma primeira frase que é uma ressalva, um ponteiro ou uma negação que nunca diz o que acontece no lugar deixa esse leitor sem nada. + +Em um bloco compacto de bullets, cada frase de um bullet fica no tópico da introdução dele. Um fato de outro tópico abre um bullet próprio. + +- Antes: `Criar uma application não atende nada.` +- Depois: `Criar uma application não atende nada sozinho: uma application trata só as requisições de um workload cujo deployment a nomeia.` + +## Apresente um termo novo por frase + +Uma frase que cria dois termos obriga o leitor a aprender os dois ao mesmo tempo e a mantê-los separados. Apresente um termo novo por frase e, depois disso, mantenha um nome para cada coisa. + +- Antes: `O Image Processor constrói uma nova imagem, a imagem derivada, a partir da imagem original na sua origem, a imagem de origem.` +- Depois: `O Image Processor constrói cada imagem que entrega a partir de uma imagem na sua origem, a imagem de origem. A imagem que ele entrega é a imagem derivada.` + ## Use uma lista vertical para uma sequência Formate três ou mais passos, condições ou alternativas como uma lista numerada ou com marcadores. Uma sequência em uma única frase obriga o leitor a interpretar a ordem e as ações ao mesmo tempo. @@ -89,7 +112,9 @@ Escolha um verbo para cada ação e repita esse verbo na página inteira. Uma ro - Antes: `Verifique se o build passou. Depois confira se o deploy passou.` - Depois: `Verifique se o build passou. Depois verifique se o deploy passou.` -Quando uma frase descreve um controle do Console, use o rótulo que o Console mostra. Não melhore o vocabulário da interface. +A regra vale também para os itens de uma lista. Quando uma frase seguinte repete uma lista, ela mantém as palavras da primeira: `adicione ou remova um header` e depois `adicione ou filtre headers` se lê como duas capacidades diferentes. + +Quando uma frase descreve um controle do Console, use o rótulo que o Console mostra. Não melhore o vocabulário da interface. Quando uma string da interface implica um fato, declare o fato primeiro e depois cite a string como fonte. Uma string citada sozinha deixa o leitor deduzir a regra. O ASD-STE100 acompanha suas regras com um dicionário aprovado. As regras 1.5 e 1.12 permitem que um projeto aprove seus próprios nomes técnicos e verbos técnicos. A Azion usa essa permissão: o vocabulário aprovado está em [Escolha de palavras](/pt-br/documentacao/guia-de-estilo/escrita/escolha-de-palavras/) e em [Terminologia da documentação](/pt-br/documentacao/guia-de-estilo/escrita/terminologia/). @@ -102,8 +127,11 @@ Confirme cada ponto antes de publicar a página: - Cada agrupamento de substantivos tem no máximo três palavras, com um nome de recurso da plataforma contado como uma. - Cada frase mantém o sujeito, o verbo e os artigos. - Cada parágrafo cobre um tópico em no máximo seis frases. +- Cada frase continua o tópico da anterior, ou abre com a palavra que nomeia a mudança. +- As primeiras frases dos parágrafos e as introduções dos bullets, lidas sozinhas, carregam cada seção. +- Cada frase apresenta no máximo um termo novo. - Cada sequência de três ou mais itens é uma lista vertical. -- Cada ação mantém o mesmo verbo na página inteira. +- Cada ação mantém o mesmo verbo na página inteira, e cada lista repetida mantém as palavras dela. ## Fontes From 2ceb1ce7720b0078eef68c8c8098b215a31d2dab Mon Sep 17 00:00:00 2001 From: Marcus Souza Date: Fri, 6 Nov 2026 11:55:38 -0300 Subject: [PATCH 4/5] docs(style-guide): settle four rules the guide stated two ways Each pair of pages now says one thing, in en and pt-br: - Reference pages: a version notice comes from the version snippets, never from a hand-written caution, as Components states. - Components: the changelog entry example uses description="Version 1.3.0", as Changelog pages states. - Changelog pages: a change to a Product nested in a Platform Resource opens with the Product as the subject. - Headings: an acronym is spelled out once per page, at its first mention, so a later heading that carries it needs no second expansion. --- .../docs/src/content/docs/en/pages/style-guide/components.mdx | 2 +- .../content/docs/en/pages/style-guide/content/changelog.mdx | 4 ++-- .../content/docs/en/pages/style-guide/content/reference.mdx | 2 +- .../content/docs/en/pages/style-guide/formatting/headings.mdx | 2 +- .../content/docs/pt-br/pages/guia-de-estilo/componentes.mdx | 2 +- .../docs/pt-br/pages/guia-de-estilo/conteudo/changelog.mdx | 4 ++-- .../docs/pt-br/pages/guia-de-estilo/conteudo/referencia.mdx | 2 +- .../docs/pt-br/pages/guia-de-estilo/formatacao/titulos.mdx | 2 +- 8 files changed, 10 insertions(+), 10 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 27d6792e7f..663d679c16 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 @@ -257,7 +257,7 @@ One dated entry: label and version on the left, the notes on the right, with an ```mdx import DocUpdate from '@aziontech/webkit/doc-update' - + **Bot Manager** now ships nine new static rules and two new arguments. 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 b7f58e37c2..7a47ebad5f 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 @@ -37,7 +37,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`. -- **The opening sentence**: `**** now s .`, plus the concrete detail: the flag, the field, or the default. +- **The opening sentence**: `**** now s .`, plus the concrete detail: the flag, the field, or the default. When the change belongs to a Product nested in the Platform Resource, the Product 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. - **The closing link**: `For more information, refer to [](/en/documentation/.../).` @@ -70,7 +70,7 @@ For more information, refer to [](/en/documentation/.../). ## Rules -- **Open with the Platform Resource as the subject.** `**** now s .` Present tense, never `we`, never `Azion is excited to`. +- **Open with the element that changed as the subject.** `**** now s .` A change to a Product nested in the Platform Resource opens with the Product: `**Bot Manager** now…`. Present tense, never `we`, never `Azion is excited to`. - **State who is not affected.** A reader's first question about any change is whether it breaks them; answer it before they ask. - **Show migration or opt-in steps when the surface changed.** An API, CLI, or configuration change gets a code sample; two lines is enough. - **Close every entry with the documentation link.** An entry that documents the feature in full is a page filed in the wrong place. 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 1d5b30aa9c..9415f4b32a 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 @@ -43,7 +43,7 @@ Descriptive: 25 words per sentence, active voice, passive only when the actor is **Optional components** -- **Asides**: a tip above the limits table when support can raise the limits, and a caution for a version or migration warning. Use no other aside. +- **Asides**: a tip above the limits table when support can raise the limits. Use no other aside: a version notice comes from one of the [version snippets](/en/documentation/style-guide/components/#version-notices), never from an aside written by hand. The sections keep this order. diff --git a/apps/docs/src/content/docs/en/pages/style-guide/formatting/headings.mdx b/apps/docs/src/content/docs/en/pages/style-guide/formatting/headings.mdx index c884670245..e510400ddc 100644 --- a/apps/docs/src/content/docs/en/pages/style-guide/formatting/headings.mdx +++ b/apps/docs/src/content/docs/en/pages/style-guide/formatting/headings.mdx @@ -59,7 +59,7 @@ A retrieval system returns one section of a page, not the whole page. The headin ## Use an acronym in a heading only when the page expands it -A heading may carry a well-established acronym, as long as the first line below it spells the term out. `Configure WAF rule sets` is a valid heading when the paragraph under it writes `Web Application Firewall (WAF)`. +A heading may carry a well-established acronym, as long as the page spells the term out once, at its first mention. When the heading is that first mention, the first line below it spells the term out: `Configure WAF rule sets` is a valid heading when the paragraph under it writes `Web Application Firewall (WAF)`. A heading whose acronym the page already spelled out above it, such as a `## WAF` section on a page that opened with `Web Application Firewall (WAF)`, needs no second expansion. [Word choice](/en/documentation/style-guide/writing/word-choice/) holds the expansion rule for the rest of the page. 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 858b4cedc5..e8b0ed8c82 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 @@ -257,7 +257,7 @@ Uma entrada datada: rótulo e versão à esquerda, as notas à direita, com uma ```mdx import DocUpdate from '@aziontech/webkit/doc-update' - + **Bot Manager** agora traz nove novas regras estáticas e dois novos argumentos. 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 94f9c0f0db..aedb7e6c24 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 @@ -37,7 +37,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`. -- **A frase de abertura**: `**** agora .`, com o detalhe concreto: a flag, o campo ou o valor padrão. +- **A frase de abertura**: `**** agora .`, com o detalhe concreto: a flag, o campo ou o valor padrão. Quando a mudança é de um produto aninhado no recurso da plataforma, o produto é 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. - **O link de fechamento**: `Para mais informações, consulte [](/pt-br/documentacao/.../).` @@ -70,7 +70,7 @@ Para mais informações, consulte [](/pt-br/ ## Regras -- **Abra com o recurso da plataforma como sujeito.** `**** agora .` Tempo presente, nunca `nós`, nunca `a Azion tem o prazer de`. +- **Abra com o elemento que mudou como sujeito.** `**** agora .` Uma mudança em um produto aninhado no recurso da plataforma abre com o produto: `**Bot Manager** agora…`. Tempo presente, nunca `nós`, nunca `a Azion tem o prazer de`. - **Diga quem não é afetado.** A primeira pergunta do leitor sobre qualquer mudança é se ela o quebra; responda antes que ele pergunte. - **Mostre a migração ou a adesão quando a superfície mudou.** Uma mudança de API, CLI ou configuração recebe um exemplo de código; duas linhas bastam. - **Feche cada entrada com o link da documentação.** Uma entrada que documenta a funcionalidade por completo é uma página arquivada no lugar errado. 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 ea6d8fbaa2..0e4fae71ca 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 @@ -43,7 +43,7 @@ Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é **Componentes opcionais** -- **Asides**: uma dica acima da tabela de limites quando o suporte pode aumentar os limites, e um aviso de atenção para uma mudança de versão ou de migração. Não use outros asides. +- **Asides**: uma dica acima da tabela de limites quando o suporte pode aumentar os limites. Não use outros asides: um aviso de versão vem de um dos [snippets de versão](/pt-br/documentacao/guia-de-estilo/componentes/#avisos-de-versao), nunca de um aside escrito à mão. As seções mantêm essa ordem. diff --git a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/titulos.mdx b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/titulos.mdx index ddc5879589..9e0ec487bd 100644 --- a/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/titulos.mdx +++ b/apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/formatacao/titulos.mdx @@ -59,7 +59,7 @@ Um sistema de busca retorna uma seção da página, não a página inteira. O t ## Use uma sigla em um título só quando a página a expande -Um título pode carregar uma sigla consagrada, desde que a primeira linha abaixo dele escreva o termo por extenso. `Configure conjuntos de regras do WAF` é um título válido quando o parágrafo abaixo escreve `Web Application Firewall (WAF)`. +Um título pode carregar uma sigla consagrada, desde que a página escreva o termo por extenso uma vez, na primeira menção. Quando o título é essa primeira menção, a primeira linha abaixo dele escreve o termo por extenso: `Configure conjuntos de regras do WAF` é um título válido quando o parágrafo abaixo escreve `Web Application Firewall (WAF)`. Um título cuja sigla a página já escreveu por extenso acima dele, como uma seção `## WAF` em uma página que abriu com `Web Application Firewall (WAF)`, não precisa de uma segunda expansão. [Escolha de palavras](/pt-br/documentacao/guia-de-estilo/escrita/escolha-de-palavras/) tem a regra de expansão para o resto da página. From 6bba008b151b84cd08863f101dbc2e58840b218a Mon Sep 17 00:00:00 2001 From: Marcus Souza Date: Fri, 6 Nov 2026 12:47:07 -0300 Subject: [PATCH 5/5] docs(governance): restore the checklist PR template and give agents its format A contributor who drafts a pull request with an agent now gets the review checklist without asking for it: - The PR template returns to What & why, Type of change, and Author checklist, the #2307 format that CONTRIBUTING, GOVERNANCE, and AGENTS.md still call the review contract. The URL guidance from the short template becomes a comment on the redirect row. - AGENTS.md gains "The description": write in the template's format, keep every checklist row verbatim, explain a row that is not true on the same line, and write to pr.md when the agent does not open the PR. - CLAUDE.md imports AGENTS.md, because Claude Code reads only CLAUDE.md when both files exist. - AGENTS.md names the current redirect folder, apps/docs/redirects/, and CONTRIBUTING points to the redirect row instead of the removed section. - .gitignore ignores /pr.md. --- .github/CONTRIBUTING.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 29 ++++++++++++++++++++--------- .gitignore | 3 +++ AGENTS.md | 28 ++++++++++++++++++++++++---- CLAUDE.md | 6 ++++++ 5 files changed, 54 insertions(+), 14 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 432bd465eb..f3e2fd3cfd 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -36,7 +36,7 @@ pnpm build:local # build + frontmatter validation (CI runs this too) pnpm lint:slugcheck # permalink rules ``` -- Changed a permalink or moved a page? **Add the redirect in this PR**, in the highest-numbered file of `apps/docs/redirects/{en,pt-br}/`, and list it under **URL changes and redirects** in the PR description. +- Changed a permalink or moved a page? **Add the redirect in this PR**, in the highest-numbered file of `apps/docs/redirects/{en,pt-br}/`, and list it on the redirect row of the PR checklist. - Can't update `pt-br` yourself? Create the follow-up `i18n` issue and link it in the PR checklist. ## The PR diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fb61af6cb5..cab10de5d5 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,26 @@ -## Summary +## What & why - +**Related issue:** +**Pages affected:** -## How to test + - +## Type of change -## URL changes and redirects +- [ ] 🆕 New content (`feat`) +- [ ] 🩹 Fix (`fix`) — typo, broken link, wrong information +- [ ] ♻️ Content update (`docs`) — rewrite, expansion, upkeep +- [ ] 🌐 Translation sync (`i18n`) +- [ ] 🏗️ Platform / structure (`refactor` / `chore`) — reviewed by UXE, no content mixed in - +## Author checklist -## Notes - - +- [ ] PR title follows `type(scope): summary` (see [GOVERNANCE.md §4](GOVERNANCE.md)) +- [ ] Frontmatter complete: `title`, `description`, `meta_tags`, `namespace`, `permalink`, `last_reviewed` +- [ ] No legacy "edge-" product names in the copy +- [ ] How-to/tutorial content includes at least one runnable, copy-paste-tested code block +- [ ] Screenshots (if any) have alt text and follow image standards +- [ ] Internal links are relative and resolve locally +- [ ] **If any permalink changed or page moved: redirect added in this PR** +- [ ] **i18n:** `pt-br` updated in this PR **or** follow-up `i18n` issue created: +- [ ] I ran `pnpm build:local` (build + frontmatter check) without errors diff --git a/.gitignore b/.gitignore index f665bc7ee8..00caa6ecd0 100644 --- a/.gitignore +++ b/.gitignore @@ -62,4 +62,7 @@ reports/ .working-files/* +# A pull request description an agent drafts for the person who opens the PR (see AGENTS.md). +/pr.md + apps/docs/src/consts.ts diff --git a/AGENTS.md b/AGENTS.md index f3acb9359b..50346e13f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,7 @@ preferences. | `apps/docs/src/content/docs/en` · `.../pt-br` | every published page, as `.mdx` | | `apps/docs/src/nav` | the navigation trees that build the sidebars | | `apps/docs/src/pages` | routes, including the `.md` twins, `llms.txt`, and the sitemaps | -| `apps/redirects-massive/src/redirects/{en,pt-br}/doc.json` | the redirect map | +| `apps/docs/redirects/{en,pt-br}/*.json` | the redirect map, in numbered files | | `.claude/rules/webkit-*.md` · `CLAUDE.md` | the design system rules, for UI work only | ## Writing or changing a page @@ -36,8 +36,8 @@ preferences. requires `description`, `meta_tags`, `namespace`, and `permalink`, and reviewers hold you to it. `namespace` pairs a page with its translation, so the two language versions share one. - **Changing a `permalink` or moving a page requires a redirect in the same pull request**, in - `apps/redirects-massive/src/redirects/{en,pt-br}/doc.json`. A permalink change without one is - a broken build. + the highest-numbered file of `apps/docs/redirects/{en,pt-br}/`. A permalink change without one + is a broken build. - **Register a new page in a navigation tree** under `apps/docs/src/nav`, or nothing links to it and it reaches no index. - **Internal links are root-relative** (`/en/documentation/...`) and must resolve. @@ -71,10 +71,30 @@ Run a script of another app with `pnpm -F