From f225ad373c81c7287aa38a3e3e1f4c7f04404bd8 Mon Sep 17 00:00:00 2001 From: Marcus Souza Date: Mon, 28 Sep 2026 21:18:39 -0300 Subject: [PATCH] docs(style-guide): bring the public guide to the platform taxonomy Apply the four platform terms (Platform, Product, Platform Resource, Feature) and the Solution > Use Case > Reference Architecture content tree to the style guide, in English and Portuguese. - Terminology: replace "Name a module as a product" with the resource nomenclature, the four-term table, and the scope of the retired module and add-on terms. - Use cases and architecture pages come from the Use Case catalog: title, scenario, products, summary, and components; catalog-first routing against multi-product guides; how to request an entry. - Slot 4 is Features; resource-type sections follow the skeleton. - Every "distributed network" and "edge node" in examples becomes Azion's distributed infrastructure and data center. - Troubleshooting headings carry error strings as plain text, with the rule added to Headings. --- .../docs/en/pages/style-guide/components.mdx | 10 ++-- .../style-guide/content/architecture.mdx | 54 +++++++++--------- .../pages/style-guide/content/changelog.mdx | 6 +- .../content/choose-a-content-type.mdx | 13 +++-- .../en/pages/style-guide/content/concept.mdx | 10 ++-- .../en/pages/style-guide/content/glossary.mdx | 2 +- .../content/information-architecture.mdx | 12 ++-- .../content/multi-product-guides.mdx | 14 ++--- .../style-guide/content/navigation-hubs.mdx | 4 +- .../en/pages/style-guide/content/overview.mdx | 6 +- .../pages/style-guide/content/quickstart.mdx | 2 +- .../style-guide/content/troubleshooting.mdx | 8 +-- .../pages/style-guide/content/tutorials.mdx | 2 +- .../pages/style-guide/content/use-cases.mdx | 52 ++++++++++------- .../style-guide/conventions/bilingual.mdx | 2 +- .../pages/style-guide/formatting/headings.mdx | 6 ++ .../en/pages/style-guide/formatting/text.mdx | 2 +- .../docs/en/pages/style-guide/index.mdx | 2 +- .../style-guide/writing/accessibility.mdx | 2 +- .../pages/style-guide/writing/terminology.mdx | 39 +++++++++---- .../en/pages/style-guide/writing/voice.mdx | 6 +- .../pages/style-guide/writing/word-choice.mdx | 10 ++-- .../pages/guia-de-estilo/componentes.mdx | 10 ++-- .../conteudo/arquitetura-de-informacao.mdx | 12 ++-- .../guia-de-estilo/conteudo/arquitetura.mdx | 56 ++++++++++--------- .../guia-de-estilo/conteudo/casos-de-uso.mdx | 52 ++++++++++------- .../guia-de-estilo/conteudo/changelog.mdx | 6 +- .../guia-de-estilo/conteudo/conceito.mdx | 10 ++-- .../conteudo/escolher-um-tipo-de-conteudo.mdx | 13 +++-- .../guia-de-estilo/conteudo/glossario.mdx | 2 +- .../conteudo/guias-multiproduto.mdx | 14 ++--- .../conteudo/hubs-de-navegacao.mdx | 4 +- .../guia-de-estilo/conteudo/quickstart.mdx | 2 +- .../conteudo/troubleshooting.mdx | 8 +-- .../guia-de-estilo/conteudo/tutoriais.mdx | 2 +- .../guia-de-estilo/conteudo/visao-geral.mdx | 6 +- .../convencoes/paginas-bilingues.mdx | 2 +- .../guia-de-estilo/escrita/acessibilidade.mdx | 2 +- .../escrita/escolha-de-palavras.mdx | 10 ++-- .../guia-de-estilo/escrita/terminologia.mdx | 37 +++++++++--- .../pages/guia-de-estilo/escrita/voz.mdx | 6 +- .../pages/guia-de-estilo/formatacao/texto.mdx | 2 +- .../guia-de-estilo/formatacao/titulos.mdx | 6 ++ .../docs/pt-br/pages/guia-de-estilo/index.mdx | 2 +- 44 files changed, 306 insertions(+), 222 deletions(-) diff --git a/src/content/docs/en/pages/style-guide/components.mdx b/src/content/docs/en/pages/style-guide/components.mdx index 7b35b6265e..2b7a7f6889 100644 --- a/src/content/docs/en/pages/style-guide/components.mdx +++ b/src/content/docs/en/pages/style-guide/components.mdx @@ -145,8 +145,8 @@ A diagram is a `mermaid` code fence, not an image. The text reaches an agent fet ````md ```mermaid flowchart LR - Client --> Edge[Edge node] - Edge --> Origin[Origin server] + Client --> DC[Azion data center] + DC --> Origin[Origin server] ``` ```` @@ -226,7 +226,7 @@ import DocItem from '@aziontech/webkit/doc-item' - How an edge node decides what to keep and for how long. + How a data center decides what to keep and for how long. Conditions and behaviors on the request and response phases. @@ -274,7 +274,7 @@ A term in running prose that shows its definition on hover or focus, with an opt ```mdx import DocTooltip from '@aziontech/webkit/doc-tooltip' -The cache key decides what matches. +The cache key decides what matches. ``` - `client:visible` is mandatory; without it the term renders and never opens. @@ -335,7 +335,7 @@ import GlossaryFilter from '~/components/GlossaryFilter.astro' | Term | Definition | | --- | --- | -| cache key | The identifier an edge node builds from a request to decide whether two requests match the same cached object. | +| cache key | The identifier a data center builds from a request to decide whether two requests match the same cached object. | ``` diff --git a/src/content/docs/en/pages/style-guide/content/architecture.mdx b/src/content/docs/en/pages/style-guide/content/architecture.mdx index 8979478624..b0522a594a 100644 --- a/src/content/docs/en/pages/style-guide/content/architecture.mdx +++ b/src/content/docs/en/pages/style-guide/content/architecture.mdx @@ -13,7 +13,7 @@ import DocItem from '@aziontech/webkit/doc-item' ## Purpose -An architecture page shows how several products combine into one design. The reader wants to understand the shape of a solution before building it. +An architecture page shows one Reference Architecture from the Use Case catalog: how Products and Platform Resources combine into one design. The reader wants to understand the shape of the design before building it. It applies the **explanation** base form, the same form as a [concept page](/en/documentation/style-guide/content/concept/). The difference is the subject: a concept page explains one thing, an architecture page explains how many things fit together. @@ -21,14 +21,15 @@ It applies the **explanation** base form, the same form as a [concept page](/en/ Write an architecture page when: -- A solution needs more than one product, and the relationship between them is the point. +- A design needs more than one Product or Platform Resource, and the relationship between them is the point. - The reader must see the order of a request or a dataflow to understand the design. - A guide keeps redrawing the same system in prose. Do not write an architecture page when: - The subject is one product or one idea. Write a [concept page](/en/documentation/style-guide/content/concept/). -- The reader wants to build the thing. Write a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/) and link it from here. +- The reader wants to build the thing. Write the [use-case page](/en/documentation/style-guide/content/use-cases/) that builds it, or a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/), and link it from here. +- The catalog has no entry for the design. Propose it to the Use Case catalog first; the page comes after the entry. - The design cannot be drawn. A design you cannot draw is one you do not yet understand well enough to publish. ## Register @@ -37,14 +38,14 @@ Descriptive: 25 words per sentence, active voice, passive only when the actor is ## Structure -The title names the design as a noun phrase: `Content delivery on a distributed network`. The opening paragraph states what problem the design solves and for whom. +The title is the Reference Architecture name from the catalog, verbatim. That name is a noun phrase naming the system built, such as `Server-rendered headless CMS website`, never with a *Reference Architecture* suffix. The opening paragraph is the entry's Summary: what problem the design solves, and for whom. It names the Use Case the design implements, linked to the use-case page where one is published. **Required sections, in order** - **`## Architecture diagram`**: the diagram as a `mermaid` code fence, then a paragraph that reads it. - **`### Dataflow`**: a numbered walkthrough of what moves where, with six items at most. -- **`## Components`**: what each part does and why it is there. -- **`## Implementation`**: links to the how-tos, and only links. +- **`## Components`**: one entry per Component of the catalog entry, with its role. Products go by name, Platform Resources lowercase as instances, and features and integrations labeled as the catalog labels them. +- **`## Implementation`**: only links. The use-case page goes here when it builds this design, followed by the guides and Marketplace templates that implement all or part of it. A use-case page that builds a sibling design is linked from the opening paragraph, as the Use Case the architecture implements, and not here. - **`## Related resources`**: the closing section, a `DocItem` list, each row with its reason. ## Template @@ -54,7 +55,7 @@ import FrameBox from '@aziontech/webkit/frame-box' import ItemList from '@aziontech/webkit/item-list' import DocItem from '@aziontech/webkit/doc-item' - + ## Architecture diagram @@ -78,7 +79,8 @@ flowchart LR ## Implementation -- []() - . +- []() - . +- []() - . ## Related resources @@ -95,41 +97,43 @@ flowchart LR - **The diagram never stands alone.** The numbered dataflow carries the meaning, and it stays even when the diagram renders. - **Label every node and edge in words**, and never rely on color alone to carry a distinction. - **Name every component and say why it is there.** A list of product names is a parts list. -- **Link the implementation, do not inline it.** Steps belong in a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/). +- **Link the implementation, do not inline it.** Steps belong in the [use-case page](/en/documentation/style-guide/content/use-cases/) or a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/). - **Write only the sections you can confirm.** A required section whose content you cannot confirm with the team that owns the product is left out until you can, never filled with a guess. +- **Report the permalink when the page ships**, so the catalog entry's Docs field can read Published. ## Examples -- [Deploy Jamstack websites on a distributed network](/en/documentation/architectures/build-and-run-applications/deploy-jamstack-applications/): a diagram, a numbered dataflow, the components involved, and links out to the implementation. +- [Deploy Jamstack websites](/en/documentation/architectures/build-and-run-applications/deploy-jamstack-applications/): the published page the catalog maps to *Git-driven static website*. It carries a diagram, a numbered dataflow, the components involved, and links out to the implementation. -This trimmed excerpt shows the opening, the diagram section, and the dataflow: +This trimmed excerpt shows the opening, the diagram section, and the dataflow of the *Git-driven static website* page. The catalog records that Reference Architecture under the Use Case *Build and run marketing websites*. No use-case page is published yet, so the Use Case is named without a link: ````mdx -This design delivers a site's content from locations close to users. It reduces latency and the load on the origin infrastructure. Use it when your team delivers static-heavy sites and applications. +A static website whose pages and content live in a Git repository. The Azion GitHub App builds the site on every push and deploys the output to Object Storage. An application serves the output through Cache, and a previous build can be redeployed to roll back. This design implements the Use Case *Build and run marketing websites*. ## Architecture diagram ```mermaid flowchart LR - Client -->|HTTP request| Node[Azion node] - Node --> Rules[Rules Engine] - Rules --> Cache[Cache layer] - Cache -->|Cache hit| Client - Cache -->|Cache miss| Origin[Origin server] - Origin --> Cache + Repo[Git repository] -->|push| App[Azion GitHub App] + App -->|build output| Bucket[Object Storage bucket] + Client -->|HTTP request| DC[Azion data center] + DC --> Cache[Cache] + Cache -->|cache hit| Client + Cache -->|cache miss| Bucket + Bucket --> Cache ``` -The diagram shows the path of a request and its response through an application on Azion's distributed network. A client request reaches a node on Azion's distributed network, where Rules Engine and the cache layer process it. Content that is not in the cache comes from the origin server, and the response returns to the client through the same node. +The diagram carries two flows. The publish flow runs from the repository through the GitHub App to the bucket, and it moves only on a push. The request flow runs from the client to a data center on Azion's distributed infrastructure. There, Cache answers from its copy or reads the file from the bucket. ### Dataflow -A request moves through the design in this order: +Content moves through the design in this order: -1. A client sends an HTTP or HTTPS request to a domain associated with an application. -2. At the Azion node, Rules Engine processes the request. It applies cache policies and image optimization behaviors in the request phase. -3. The cache layer evaluates the request. On a cache-key match, the node delivers the object from the cache. -4. On a cache miss, the node forwards the request to the origin server. The origin responds, and the node caches the content. -5. Before the response returns to the client, Rules Engine processes the response-phase policies. The node then delivers the content to the user. +1. A push to the repository triggers the Azion GitHub App, which builds the site. +2. The GitHub App deploys the build output to the Object Storage bucket. +3. A client sends an HTTP or HTTPS request to the domain of the application that serves the bucket. +4. In the data center, Cache answers the request from its copy of the file when it holds one. +5. On a cache miss, the application reads the file from the bucket, and Cache stores it for the next request. ```` ## Related diff --git a/src/content/docs/en/pages/style-guide/content/changelog.mdx b/src/content/docs/en/pages/style-guide/content/changelog.mdx index 7b40279f50..6d4dfc5c1e 100644 --- a/src/content/docs/en/pages/style-guide/content/changelog.mdx +++ b/src/content/docs/en/pages/style-guide/content/changelog.mdx @@ -37,7 +37,7 @@ An entry sits under a date heading and runs three to six short paragraphs, with **Required components** - **A date heading**: `## , `, newest first. Dates are allowed in changelogs and only in changelogs. -- **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. - **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/.../).` @@ -54,7 +54,7 @@ An entry sits under a date heading and runs three to six short paragraphs, with ### -**** now s , . +**** now s , . @@ -67,7 +67,7 @@ For more information, refer to [](/en/documentation/.../). ## Rules -- **Open with the product as the subject.** `**** now s .` Present tense, never `we`, never `Azion is excited to`. +- **Open with the product as the subject.** `**** now s .` 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/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx b/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx index 9c3242ce4c..72ee190ee8 100644 --- a/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx +++ b/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx @@ -32,11 +32,11 @@ A page kind is a base form plus a place in the [information architecture](/en/do | [Tutorial](/en/documentation/style-guide/content/tutorials/) | Tutorial | No | Teach the product by building a goal the author chose | | [How-to guide](/en/documentation/style-guide/content/how-to-guides/) | How-to | No | Complete one task the reader arrived with | | [Multi-product guide](/en/documentation/style-guide/content/multi-product-guides/) | How-to | No | Reach a goal that crosses products, on one recommended path | -| [Use case](/en/documentation/style-guide/content/use-cases/) | How-to | No | Implement a business scenario end to end, as a spec an agent can follow | +| [Use case](/en/documentation/style-guide/content/use-cases/) | How-to | No | Build a Use Case from the catalog end to end, as a spec an agent can follow | | [Troubleshooting](/en/documentation/style-guide/content/troubleshooting/) | How-to | No | From a symptom the reader sees to a fix | | [Reference](/en/documentation/style-guide/content/reference/) | Reference | No | Look up fields, values, defaults, and limits | | [Concept](/en/documentation/style-guide/content/concept/) | Explanation | No | Understand how something works and why it is built that way | -| [Architecture](/en/documentation/style-guide/content/architecture/) | Explanation | No | How products combine into a design | +| [Architecture](/en/documentation/style-guide/content/architecture/) | Explanation | No | One Reference Architecture from the catalog: how Products and Platform Resources combine into a design | | [Changelog](/en/documentation/style-guide/content/changelog/) | Record | No | Log notable changes, append-only | | [Glossary](/en/documentation/style-guide/content/glossary/) | Reference | Yes | Define the terms the product'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 | @@ -45,7 +45,7 @@ A page kind is a base form plus a place in the [information architecture](/en/do A slot is a position in a product section; a kind is the shape of a page. The [information architecture](/en/documentation/style-guide/content/information-architecture/) lists thirteen slots, and this catalog holds thirteen kinds. Equal length is a coincidence: the two lists do not map onto each other. -Several slots share one kind. Limits, Examples, and Features and capabilities all hold reference pages, placed in different slots because readers reach them at different moments. Best practices and How it works both hold concept pages. One slot can also hold several kinds: Guides and tutorials holds a navigation hub, the how-to guides, and the tutorials. Adding a slot never adds a kind, and a page that fits no kind is a page whose content type is still undecided. +Several slots share one kind. Limits, Examples, and Features all hold reference pages, placed in different slots because readers reach them at different moments. Best practices and How it works both hold concept pages. One slot can also hold several kinds: Guides and tutorials holds a navigation hub, the how-to guides, and the tutorials. Adding a slot never adds a kind, and a page that fits no kind is a page whose content type is still undecided. ## Kinds Azion does not use @@ -53,8 +53,9 @@ Some kinds common in other documentation sets are deliberately absent, because e - **FAQ**: a list of questions is a list of pages in disguise. Route each answer to its kind, and the question becomes a heading a search can find. - **Configuration**: examples of settings and values are reference content. The kind adds a second name for the same page. -- **Design, implementation, and solution guides**: three names for content the catalog already holds. A goal that crosses products is a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/). A business scenario built end to end is a [use case](/en/documentation/style-guide/content/use-cases/). The reasoning behind a design is a [concept](/en/documentation/style-guide/content/concept/) or an [architecture](/en/documentation/style-guide/content/architecture/) page. +- **Design, implementation, and solution guides**: three names for content the catalog already holds. A goal that crosses products is a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/). A Use Case from the catalog, built end to end, is a [use case](/en/documentation/style-guide/content/use-cases/). The reasoning behind a design is a [concept](/en/documentation/style-guide/content/concept/) or an [architecture](/en/documentation/style-guide/content/architecture/) page. - **Third-party integration guide**: a how-to guide that crosses a vendor's interface. The [third-party rules](/en/documentation/style-guide/content/how-to-guides/) cover it. +- **Solution page**: a Solution lives on the website, not in the documentation. Here a Solution is the label of a Guides area and of an Architectures group. The pages are the use cases and architectures under it. - **API guidelines** are not covered by this guide yet. ## Separate tutorials from how-to guides @@ -81,9 +82,9 @@ Both take the how-to base form and both cross products, so the split is worth st A multi-product guide starts from a technical goal. The reader knows what they want to build and needs the route across products. It ends when the task is done. -A use case starts from a business scenario. The reader arrives with a situation, not a task. The page names the products the scenario needs, shows the architecture, configures it, and proves it works. It is written as a specification an agent can execute. That is why it carries a requirements table and a measurable outcome, which the multi-product guide does not. +A use case starts from a catalog entry: a customer situation the Use Case catalog already names and places under its Solution. The reader arrives with a situation, not a task. The page names the products the scenario needs, shows the architecture, configures it, and proves it works. It is written as a specification an agent can execute. That is why it carries a requirements table and a measurable outcome, which the multi-product guide does not. -The test: if you can state the goal without naming an industry or a business situation, it is a multi-product guide. +The test runs in two steps. First match the goal to the Use Case catalog: an entry makes the page a use case, whatever the wording of the goal. With no entry, a goal the reader states without a customer situation is a multi-product guide. A customer situation the catalog should carry is a proposal for a new entry, not a page. ## Keep one form per page diff --git a/src/content/docs/en/pages/style-guide/content/concept.mdx b/src/content/docs/en/pages/style-guide/content/concept.mdx index 92f121f742..06bb5c9d79 100644 --- a/src/content/docs/en/pages/style-guide/content/concept.mdx +++ b/src/content/docs/en/pages/style-guide/content/concept.mdx @@ -15,7 +15,7 @@ import DocItem from '@aziontech/webkit/doc-item' A concept page builds understanding. The reader is not in the middle of a task; they want to understand how something works and why it is built that way, usually before deciding to use it. -It applies the **explanation** base form, one of the four Diátaxis forms. When a design combines several products, write an [architecture page](/en/documentation/style-guide/content/architecture/) instead: it is the same base form with a diagram and a dataflow. +It applies the **explanation** base form, one of the four Diátaxis forms. When Products and Platform Resources combine into a Reference Architecture, write an [architecture page](/en/documentation/style-guide/content/architecture/) instead: it is the same base form with a diagram and a dataflow. ## When to use @@ -29,7 +29,7 @@ Do not write a concept page when: - The reader needs to look up a value, a field, or a limit. Write a [reference page](/en/documentation/style-guide/content/reference/). - The reader needs steps for a task. Write a [how-to guide](/en/documentation/style-guide/content/how-to-guides/) or a [tutorial](/en/documentation/style-guide/content/tutorials/). -- The subject is how several products combine into a design. Write an [architecture page](/en/documentation/style-guide/content/architecture/). +- The subject is how Products and Platform Resources combine into a Reference Architecture. Write an [architecture page](/en/documentation/style-guide/content/architecture/). This is the page kind most often missing. When another kind starts to explain, write the concept page and keep that kind clean. @@ -90,7 +90,7 @@ behaves, and what it costs.> ## Rules - **Open with behavior, not framing.** State how the system behaves; never `This page explains`. -- **Explain the thing before the Azion object.** `Cache stores a copy of a response on the edge node that fetched it. The edge node answers later requests for the same object from that copy, without reaching the origin.` Only then the objects that realize it. An opening whose every subject is an Azion product or object is an inventory, not an explanation. +- **Explain the thing before the Azion object.** `Cache stores a copy of a response in the data center that fetched it. That data center answers later requests for the same object from that copy, without reaching the origin.` Only then the objects that realize it. An opening whose every subject is an Azion product or object is an inventory, not an explanation. - **Mirror the roadmap.** One noun-phrase `##` per mechanism, in the order the roadmap sentence names them. A section cut from the page is cut from the roadmap in the same edit. - **State the tradeoff.** Every design choice costs something, so say what. An explanation that presents only upsides is marketing. - **No procedures.** Link the [how-to guide](/en/documentation/style-guide/content/how-to-guides/) that applies the concept. @@ -106,13 +106,13 @@ 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 module that creates an additional cache layer between Azion's distributed network and the origin servers. With the module active, 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. The module is available on request: activation goes through the Sales team. +**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. Its behavior depends on five mechanisms: the cache layers, the second-layer region, the TTL requirements, the Bypass Cache limitation, and the purge order. ## Cache layers -End users send requests to Azion's distributed network, where content is cached. Without Tiered Cache, a request that misses the first cache layer goes to the origin. Tiered Cache adds a second cache layer between that first layer and the origin servers. The tiered layer can answer a request that misses the first layer, so the request does not reach the origin. Content stays cached for longer periods, and the origin receives fewer requests. +End users send requests to Azion's distributed infrastructure, where content is cached. Without Tiered Cache, a request that misses the first cache layer goes to the origin. Tiered Cache adds a second cache layer between that first layer and the origin servers. The tiered layer can answer a request that misses the first layer, so the request does not reach the origin. Content stays cached for longer periods, and the origin receives fewer requests. ``` ## Related diff --git a/src/content/docs/en/pages/style-guide/content/glossary.mdx b/src/content/docs/en/pages/style-guide/content/glossary.mdx index 0cc8727f93..4dd4a98113 100644 --- a/src/content/docs/en/pages/style-guide/content/glossary.mdx +++ b/src/content/docs/en/pages/style-guide/content/glossary.mdx @@ -15,7 +15,7 @@ import DocItem from '@aziontech/webkit/doc-item' A glossary defines the terms one product's documentation uses. It is look-up material: the reader arrives with a word, finds its definition, and follows a link when the definition is not enough. -A glossary holds Azion-specific vocabulary: products, modules, platform objects, and the terms Azion uses in its own way. A generic industry term, such as CDN, serverless, or virtual machine, belongs to the [Learning Center](https://www.azion.com/en/learning/), not to a documentation glossary. A term the industry also uses, but Azion uses differently, keeps its entry here and links the Learning Center for the generic sense. +A glossary holds Azion-specific vocabulary: Products, Platform Resources, Features, and the terms Azion uses in its own way. A generic industry term, such as CDN, serverless, or virtual machine, belongs to the [Learning Center](https://www.azion.com/en/learning/), not to a documentation glossary. A term the industry also uses, but Azion uses differently, keeps its entry here and links the Learning Center for the generic sense. It is not a naming-rules page. Product naming belongs to [Documentation terminology](/en/documentation/style-guide/writing/terminology/); the glossary defines what terms mean for the reader. diff --git a/src/content/docs/en/pages/style-guide/content/information-architecture.mdx b/src/content/docs/en/pages/style-guide/content/information-architecture.mdx index cf290ea648..90ae13c393 100644 --- a/src/content/docs/en/pages/style-guide/content/information-architecture.mdx +++ b/src/content/docs/en/pages/style-guide/content/information-architecture.mdx @@ -16,12 +16,14 @@ Two principles organize everything. Sections follow the order of the reader's jo Every product section follows this order. The table shows what each slot holds and when it exists. +A Platform Resource type with a section of its own (Applications, Firewall, Connectors, Workloads, Custom Pages, Certificate Manager) follows the same skeleton. Its Overview describes the resource type, its Quickstart creates the first instance, and Glossary, Pricing, and Changelog are required as they are for a product. The Products enabled on the resource keep sections of their own, and the resource section lists them as cross-links in one same-type group. + | Order | Slot | Required | Holds | | --- | --- | --- | --- | | 1 | Overview | Yes | The product root page: what the product is, what it does, when to use it | | 2 | Quickstart | Yes | [Quickstart pages](/en/documentation/style-guide/content/quickstart/): from not using the product to the smallest working result | | 3 | How it works | When the product needs explaining | [Concept pages](/en/documentation/style-guide/content/concept/): the mechanism, the tradeoff, how to choose between options | -| 4 | Features and capabilities | When the product has feature surfaces | The product's own sub-surfaces, such as a rules engine, a cache, or a runtime API | +| 4 | Features | When the product has feature surfaces | The product's own sub-surfaces, such as a rules engine, a cache, or a runtime API | | 5 | Guides and tutorials | When the product has tasks | One [navigation hub](/en/documentation/style-guide/content/navigation-hubs/) listing the [how-to guides](/en/documentation/style-guide/content/how-to-guides/) and the [tutorials](/en/documentation/style-guide/content/tutorials/) | | 6 | Examples | Optional | Working code the reader copies, grouped by language or by task | | 7 | Reference | When the product has settings | [Reference pages](/en/documentation/style-guide/content/reference/): fields, values, defaults | @@ -47,7 +49,7 @@ Other rows may group the same way. A group is a menu parent, not a page, and it 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. -A product with modules repeats the pattern one level down. A module with its own surface gets a subsection with the same skeleton, reduced to the parts it needs. +A feature with its own surface repeats the pattern one level down: Tiered Cache under Cache, with the same skeleton reduced to the parts it needs. A Product enabled on a Platform Resource keeps a section of its own. Quickstart carries the interface inside the page. A product whose first run goes through Azion Console, the Azion CLI, or the API keeps one page and selects the interface with tabs, so the slot holds one row and one URL. The slot splits only when the interfaces cannot share one stage skeleton, and for an AI agent, whose path is driven by prompt and shares no stage with the others. Those pages group under Quickstart, with Console first; the group is a sidebar parent, not a page. [Quickstart pages](/en/documentation/style-guide/content/quickstart/) holds the test. @@ -59,7 +61,7 @@ The platform onboarding section at `/documentation/get-started/` is a different - **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. - **Never add a slot to complete the pattern**, and never keep an empty one as a placeholder. -- **Grow by splitting a slot the section already has:** Guides and tutorials into named task groups on the hub page, Features and capabilities by surface. Quickstart grows inside its page, by interface tabs, and splits only when the stages cannot be shared. +- **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. - **The thirteen never grow in number.** ## Pricing and limits @@ -78,8 +80,8 @@ Content that no single product owns lives beside the products, not inside one of - The page documents one product: place it in that product's section, in the slot its content type indicates. - The page explains the platform, accounts, or billing: it goes in Fundamentals. - The page diagnoses platform problems or reaches the support team: it goes in Support. -- The page solves a business scenario end to end: it is a [use case](/en/documentation/style-guide/content/use-cases/), and it goes in Guides. -- The page shows how products combine into a design: it goes in Architectures. +- The page builds a Use Case from the catalog: it is a [use case](/en/documentation/style-guide/content/use-cases/), and it goes in Guides, under the Solution area of its entry. +- The page shows one Reference Architecture from the catalog, how Products and Platform Resources combine into a design: it goes in Architectures, under its Solution. - The page collects links for an area: it is a [navigation hub](/en/documentation/style-guide/content/navigation-hubs/), and it needs a real audience before it exists. When no section fits, open an issue before you create one. A new section changes navigation for every reader. diff --git a/src/content/docs/en/pages/style-guide/content/multi-product-guides.mdx b/src/content/docs/en/pages/style-guide/content/multi-product-guides.mdx index e987f3c426..da5ea74da0 100644 --- a/src/content/docs/en/pages/style-guide/content/multi-product-guides.mdx +++ b/src/content/docs/en/pages/style-guide/content/multi-product-guides.mdx @@ -29,7 +29,7 @@ Do not write a multi-product guide when: - One product reaches the goal. Write a [how-to guide](/en/documentation/style-guide/content/how-to-guides/) in that product's section. - The reader wants to understand the design rather than build it. Write an [architecture page](/en/documentation/style-guide/content/architecture/). -- The goal is a commercial scenario with a business frame. That is a use case, and it takes the same base form with an added scenario and a requirements table. +- The goal is a Use Case from the catalog. That is a use case, and it takes the same base form with an added scenario and a requirements table. ## Register @@ -39,7 +39,7 @@ Procedural: 20 words per sentence, one instruction per step, imperative and acti **Required components** -- **Problem opening**: one or two sentences stating the problem, before any product name. The products enter after the problem, by role: "You configure caching with **Applications** and request filtering with **Firewall**." +- **Problem opening**: one or two sentences stating the problem, before any product name. The products, and the resources they are configured on, enter after the problem, by role: "You configure caching on the application and request filtering on the firewall." - **Prerequisites**: a `## Prerequisites` section, bulleted; each item is a link or a one-line command. A single prerequisite is a sentence, not a list. - **Stages**: one `##` per workflow stage, never per product, each an imperative heading naming the stage. Each stage names its product on entry, holds an ordinary procedure, and stands alone. - **Outcome sentence**: every procedure ends by stating what the reader now has or sees. @@ -96,7 +96,7 @@ Separate the major sections of the page with a `---` rule, and never place one d ## Rules - **Title the goal, not the products.** The title states the goal in plain language, with no product names: `Serve a site with cached content and a protected checkout`. The reader searches for the outcome. -- **State the problem first.** One or two sentences, then the products by role: "You configure caching with **Applications** and request filtering with **Firewall**." +- **State the problem first.** One or two sentences, then the products and their resources by role: "You configure caching on the application and request filtering on the firewall." - **Order by the workflow, never by the product catalog.** A page organized product-by-product is a bundle of how-tos wearing one title. - **Name the product at each stage.** An unqualified interface name is ambiguous once the page crosses products. - **Stay a how-to.** The products are the route, not the subject. A paragraph of product background belongs to a concept page; link it. @@ -111,7 +111,7 @@ Separate the major sections of the page with a `---` rule, and never place one d This excerpt shows the problem opening, the prerequisites, and the first workflow stage: ```mdx -Each route of a storefront needs a different rule. The catalogue can answer from cache, the cart must not, and the checkout needs a rate limit. You configure caching with **Applications** and request filtering with **Firewall**. +Each route of a storefront needs a different rule. The catalogue can answer from cache, the cart must not, and the checkout needs a rate limit. You configure caching on the application and request filtering on the firewall. ## Prerequisites @@ -120,16 +120,16 @@ Each route of a storefront needs a different rule. The catalogue can answer from ## Turn on Application Accelerator -The **Bypass Cache** behavior requires the **Application Accelerator** module of **Applications**. +The **Bypass Cache** behavior requires **Application Accelerator** enabled for the application. -To turn on the module: +To enable it: 1. Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**. 2. In the **Main Settings** tab, go to the **Modules** section. 3. Turn on the **Application Accelerator** switch. 4. Select **Save**. -The Application Accelerator module is enabled for the application. +Application Accelerator is enabled for the application. ``` ## Related diff --git a/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx b/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx index 211c3b09c4..f6e502a3f7 100644 --- a/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx +++ b/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx @@ -20,7 +20,7 @@ It applies **no** Diátaxis base form. A hub does not teach, instruct, describe, ## When to use - Write a hub when a section holds more pages than a sidebar makes legible. -- Write one for a section that gathers pages from several products, such as a solutions or architectures index. +- Write one for a section that gathers pages from several products, such as a Solution area of the guides hub, or the architectures index. - Write one for the Guides and tutorials slot of a product section, which is a single sidebar row pointing at a hub rather than a dropdown. [Information architecture](/en/documentation/style-guide/content/information-architecture/) holds that rule. Do not write a hub when: @@ -103,7 +103,7 @@ import GuidesTable from '~/components/GuidesTable.astro' ## Examples -- [Architectures](/en/documentation/architectures/) - One line of orientation, then the designs grouped by the problem they solve. +- [Architectures](/en/documentation/architectures/) - One line of orientation, then the designs grouped by Solution. - [Cache guides and tutorials](/en/documentation/build/cache/guides/) - The table shape: one sentence, then every guide and tutorial with its date and difficulty. An Object Storage hub, trimmed to its orientation sentence and first group: diff --git a/src/content/docs/en/pages/style-guide/content/overview.mdx b/src/content/docs/en/pages/style-guide/content/overview.mdx index 61025dfe47..e1bd6765ee 100644 --- a/src/content/docs/en/pages/style-guide/content/overview.mdx +++ b/src/content/docs/en/pages/style-guide/content/overview.mdx @@ -24,7 +24,7 @@ Every product has one. It is the page a reader lands on from search, from the si Do not write an Overview when: -- The subject is a module or a feature. That belongs in a [reference page](/en/documentation/style-guide/content/reference/) inside the product section. +- The subject is a feature. That belongs in a [reference page](/en/documentation/style-guide/content/reference/) inside the product section. - The page would walk the reader through a task. That is a [how-to guide](/en/documentation/style-guide/content/how-to-guides/), linked from here. - The page would only list links. That is a [navigation hub](/en/documentation/style-guide/content/navigation-hubs/). @@ -104,7 +104,7 @@ import DocCard from '@aziontech/webkit/doc-card' - **The title is the product name, a noun.** Not "documentation", not a gerund. - **Explain the thing before the product.** The first sentence says what the class of thing is; the product sentence follows it. Cover the product name: what remains must be true of any vendor's version of the thing. - **Name the product by the second sentence at the latest, 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 is this and what does Azion's version do, what am I writing, how does it get called, what can it do and where does it stop, where do I go now. An outline that reproduces the product's module list is a catalog: it answers "what do we sell" instead of "what am I deciding". +- **Organize by the reader's questions, not by your feature list.** The sections answer, in order: what is this and what does Azion's version do, what am I writing, how does it get called, what can it do and where does it stop, where do I go now. An outline that reproduces the product's feature list is a catalog: it answers "what do we sell" instead of "what am I deciding". - **The questions shape the sections; they never become the headings.** A heading is a short noun phrase, never a question: `Function structure`, not `What a function looks like`. - **Draw the diagram from the documented sequence.** A diagram of a sequence the documentation already states in prose is a change of notation, not a new fact. Every node and every arrow matches a step the product performs, and the numbered walk carries the meaning if the figure does not render. - **Send the reader to the [Quickstart](/en/documentation/style-guide/content/quickstart/)**, in the CTAs and again in the router. @@ -117,7 +117,7 @@ This excerpt of the **Functions** overview shows the definition block in two lay ```mdx A function is code that runs when a request arrives, on infrastructure Azion operates. You write a handler that receives the request and returns a response. The platform starts the handler 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/). -**Functions** runs that code in JavaScript on Azion's distributed network, inside the request path of an application or a firewall. Use Functions to build APIs, manipulate request and response headers, apply logic from request metadata, or block traffic before it reaches your application. +**Functions** runs that code in JavaScript on Azion's distributed infrastructure, inside the request path of an application or a firewall. 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/src/content/docs/en/pages/style-guide/content/quickstart.mdx b/src/content/docs/en/pages/style-guide/content/quickstart.mdx index e9d17d2923..3e1efb7cf0 100644 --- a/src/content/docs/en/pages/style-guide/content/quickstart.mdx +++ b/src/content/docs/en/pages/style-guide/content/quickstart.mdx @@ -24,7 +24,7 @@ Quickstart is the per-product slot. The platform onboarding section at `/documen - Add an interface panel when a product's first run goes through Azion Console, the Azion CLI, or the API. - Do not write a Quickstart page for a task the reader already has in mind. That task needs a [how-to guide](/en/documentation/style-guide/content/how-to-guides/). - Do not compare interfaces or offer options inside a panel. A panel documents one interface, end to end. -- Do not write a separate Quickstart page for a module or a feature. The pattern covers one whole product. +- Do not write a separate Quickstart page for a feature. The pattern covers one whole product. ## Register diff --git a/src/content/docs/en/pages/style-guide/content/troubleshooting.mdx b/src/content/docs/en/pages/style-guide/content/troubleshooting.mdx index e25e6c275e..aa8b35af1b 100644 --- a/src/content/docs/en/pages/style-guide/content/troubleshooting.mdx +++ b/src/content/docs/en/pages/style-guide/content/troubleshooting.mdx @@ -35,7 +35,7 @@ The title is shaped `Troubleshoot `: `Troubleshoot WAF - **Opening move**: one scope sentence naming the product and the class of symptoms the page covers. - **Symptom sections**: one `##` per symptom, each fully self-contained and readable in any order. -- **Symptom headings**: a noun phrase stating the observable behavior, quoting error strings verbatim in monospace: `` ## `403 Forbidden` on legitimate requests ``. +- **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. - **The fix**: a numbered procedure, or remedy bullets shaped `****: what it does and its link`. @@ -61,7 +61,7 @@ symptoms the page covers.] --- -## +## @@ -103,7 +103,7 @@ Separate the symptom sections with a `---` rule, and never place one directly af - **Name the page after the symptom class.** The title is shaped `Troubleshoot `. - **Open with one scope sentence** naming the product and the class of symptoms the page covers. -- **Name the symptom, not the cause.** The reader searches with what they see; quote error strings verbatim in monospace. +- **Name the symptom, not the cause.** The reader searches with what they see. Quote error strings verbatim: in body text in monospace, in a heading as plain text, because backticks render a code chip that breaks the heading line. - **Make each symptom section stand alone.** The reader arrives at any section first; name the subject in each one. - **Keep the order inside each section**: the symptom, the cause, the fix, the outcome. - **Order causes by frequency.** When a symptom has more than one cause, the reader tries fixes top-down. @@ -121,7 +121,7 @@ This excerpt of a troubleshooting page for WAF false positives shows the opening --- -## `403 Forbidden` on legitimate requests +## 403 Forbidden on legitimate requests After you turn on the WAF in blocking mode, legitimate requests receive a `403 Forbidden` response. diff --git a/src/content/docs/en/pages/style-guide/content/tutorials.mdx b/src/content/docs/en/pages/style-guide/content/tutorials.mdx index 702fcb517c..60e3366530 100644 --- a/src/content/docs/en/pages/style-guide/content/tutorials.mdx +++ b/src/content/docs/en/pages/style-guide/content/tutorials.mdx @@ -35,7 +35,7 @@ A tutorial teaches the product by having the reader build something that works. - The reader arrived with the task already in mind. That is a [how-to guide](/en/documentation/style-guide/content/how-to-guides/). - The page activates a product for the first time. That is a [quickstart](/en/documentation/style-guide/content/quickstart/). -- The page implements a business scenario end to end. That is a [use case](/en/documentation/style-guide/content/use-cases/). +- The page builds a Use Case from the catalog end to end. That is a [use case](/en/documentation/style-guide/content/use-cases/). - The subject is fields, values, and defaults. That is [reference](/en/documentation/style-guide/content/reference/). - Nothing is finished at the end. Steps that end nowhere teach nothing, so find the artifact or drop the page. diff --git a/src/content/docs/en/pages/style-guide/content/use-cases.mdx b/src/content/docs/en/pages/style-guide/content/use-cases.mdx index bf7696f87c..85b4e1a8dd 100644 --- a/src/content/docs/en/pages/style-guide/content/use-cases.mdx +++ b/src/content/docs/en/pages/style-guide/content/use-cases.mdx @@ -1,7 +1,7 @@ --- title: Use cases description: >- - Write a use-case page: a business scenario turned into an executable + Write a use-case page: a Use Case from the catalog turned into an executable specification, with required products, an architecture, and measurable results. meta_tags: 'style guide, use cases, guides, spec driven documentation' @@ -14,16 +14,17 @@ import DocItem from '@aziontech/webkit/doc-item' ## Purpose -A use-case page turns a business scenario into a setup someone can build and verify. The reader arrives with a situation, not a task: a storefront that slows down during a sale, a live event that has to reach one more region. +A use-case page turns one entry of the Use Case catalog into a setup someone can build and verify. The entry gives the page its title, its scenario, its products, and the reference architectures it can build. The page never coins a use case of its own. The catalog is maintained by Azion. A writer who needs an entry, or finds one wrong, asks for it before writing the page. The request goes through the repository's issue templates, or through the catalog's owner inside Azion. The reader arrives with a situation, not a task: a storefront that slows down during a sale, a live event that has to reach one more region. A use case is a specification, not an article. It carries everything an implementer needs in one page: the products the scenario requires, the architecture, the configuration, the checks, and the metrics that show it working. That implementer is often an agent, so the page is written to be executed rather than read. -Use cases live in the Guides section, never inside one product. +Use cases live in the Guides section, never inside one product, under the Solution area of their catalog entry. The area's label is the Solution name. ## When to use **Recognize a use case by:** +- A title that is a Use Case name from the catalog, verbatim: an imperative verb phrase naming a workload, with no product names. - A reader who arrived with a business situation rather than a task. - A requirements table mapping each business need to the product that meets it. - An outcome that stays measurable after the setup works. @@ -31,7 +32,7 @@ Use cases live in the Guides section, never inside one product. **It is still a use case when:** -- It configures four things or fewer. More than four means it is two use cases. +- It configures four things or fewer. More than four means the entry is too wide for one page. - It links the generic procedure instead of repeating it here. - It ships without a demo, because none exists. Never describe a demo that does not run. @@ -39,7 +40,7 @@ Use cases live in the Guides section, never inside one product. - There is nothing to configure. The page explains a design, so write an [architecture page](/en/documentation/style-guide/content/architecture/). - The setup is a single task. That is a [how-to guide](/en/documentation/style-guide/content/how-to-guides/). -- The goal is technical and needs no business framing. That is a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/). +- The catalog has no entry for it, and the goal needs no customer situation. That is a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/). An entry makes the page a use case, whatever the wording of the goal. - The reader has no scenario, only the product. That is a [tutorial](/en/documentation/style-guide/content/tutorials/). ## Register @@ -50,11 +51,11 @@ Procedural: 20 words per sentence, one instruction per step, imperative and acti **Required components** -- **Scenario**: three to five sentences naming what the team has, what it needs, and what this page sets up. Followed by one line stating what the use case does not cover. +- **Scenario**: three to five sentences from the catalog entry's Scenario. They name the actor, the workload and the situation it is in, what this page sets up, and the measurable result. Followed by one line stating what the use case does not cover, the entry's own exclusion. - **Prerequisites**: a `## Prerequisites` section, each item a link or a one-line command where one exists. -- **Required products**: the requirements table. One row per requirement, naming the technical need, the product that meets it, and the page that documents it. -- **Reference architecture**: a `## Reference architecture` section holding a `mermaid` diagram and a numbered `### Dataflow` beneath it. -- **Configuration**: one `## Configure ` section per requirement, four at most, each holding a procedure that ends with its outcome sentence. +- **Required products**: the requirements table. One row per requirement, naming the technical need, the product that meets it, and the page that documents it. The Product column holds the Products of the catalog entry. A dependency the product documentation confirms and the entry omits goes in the table too, and the gap is reported to the catalog. The technical need names the platform resource the reader configures. +- **Reference architecture**: a `## Reference architecture` section. It opens by naming which of the entry's Reference Architectures the page builds, then holds a `mermaid` diagram and a numbered `### Dataflow`. The entry's other Reference Architectures are linked as architecture pages where one exists. +- **Configuration**: one `## Configure ` section per requirement whose setup is specific to this use case, four at most. Each holds a procedure that ends with its outcome sentence. A requirement met by a generic procedure gets no section. The requirements table links the guide that documents it, and the check stays in the verification section. - **Verification**: a `## Verify the setup` section with one check per requirement and its expected result. - **Measuring results**: a `## Measuring results` section naming the metrics that show the setup working, and where to read each one. - **Best practices**: a `## Best practices` section holding the recommendations and the reasoning behind each. @@ -80,10 +81,12 @@ Copy the template and replace each ``: import DocCardGroup from '@aziontech/webkit/doc-card-group' import DocCard from '@aziontech/webkit/doc-card' - + - + ## Prerequisites @@ -101,6 +104,8 @@ needs, and what this page sets up.> ## Reference architecture + + ```mermaid flowchart LR @@ -166,25 +171,27 @@ To : - **Write a specification, not an article.** Every value is concrete, every command runs, and no step says "depending on your setup". The reader may be an agent, and an agent cannot resolve an ambiguity by asking. - **Show the output after every command.** The reader sees what success looks like before the next step depends on it. The rule is in [Procedures](/en/documentation/style-guide/writing/procedures/). -- **Narrow the scenario to one buildable setup.** State it as `A that configures so that .` If the sentence needs an "and also", it is two use cases. +- **Narrow the scenario to one buildable setup.** State it as `A that configures so that .` If the sentence needs an "and also", the entry is too wide for one page. Write the first setup and report the width to the catalog. Do not coin a second use case. - **Start from the requirements table.** Every row is a requirement you have confirmed against the product. A requirement you cannot confirm does not go in the table. - **Inline what is specific to this use case. Link what is true for every use case.** The generic path is a link; the page holds what the scenario changes. -- **Cap the configuration at four sections.** More than four means the use case is too wide. Split it rather than raise the cap. +- **Cap the configuration at four sections.** A requirement met by a generic procedure never counts: its guide is linked from the requirements table, and its check stays in the verification section. More than four requirements that need a section of their own means the entry is too wide for one page. Narrow the setup to the Reference Architecture the page builds and report the width to the catalog. Never raise the cap, and never coin a second use case. - **Diagram in `mermaid`.** The diagram is text so that an agent reading the markdown twin gets the design, not an image reference. The numbered dataflow still carries the meaning: the diagram never stands alone. - **Separate verification from measurement.** Verification is a one-time check that the setup is correct. Measurement is the ongoing signal that it still works. - **Keep best practices as recommendations with reasons.** A recommendation without its reason is an instruction in the wrong section, and it belongs in the procedure. - **Never make a commercial claim.** No cost saving, no percentage, no competitor, no customer name, and no assertion that a configuration makes anyone compliant. - **Example figures are not limits.** A figure that frames the scenario stays in the scenario paragraph and appears nowhere else. +- **Take the title, the scenario, and the products from the catalog entry.** A request that arrives as a bare scenario, such as e-commerce or live streaming, is matched to an entry first. An entry makes the page a use case, whatever the wording of the goal. When no entry covers it, a goal that needs no customer situation is a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/). A customer situation the catalog should carry is proposed as an entry first. A use case is never coined on the page. - **Never invent a product name, a field, or a value.** Take product names from [Documentation terminology](/en/documentation/style-guide/writing/terminology/), and fields and values from the product, not from a URL or a directory path. +- **Report the permalink when the page ships**, so the catalog entry's Docs field can read Published. ## Examples -This excerpt of a use case for an e-commerce storefront shows the scenario, the not-covered line, and the requirements table: +This excerpt of the use case *Build e-commerce storefronts* builds its *Origin-hosted commerce platform storefront* reference architecture. It shows the scenario, the not-covered line, and the requirements table: ```mdx -A retail team runs a storefront on Azion and expects heavy traffic during a seasonal sale. The catalogue pages are identical for every visitor, the cart is personal, and the checkout accepts a limited number of requests per customer. This page configures caching for the catalogue, a cache bypass for the cart, and a rate limit on checkout. +A digital commerce team runs the storefront of an online store on a commerce platform it already operates. Catalog and product pages must stay fast during traffic peaks while prices and stock change, and the cart and the checkout stay dynamic. This page configures an application in front of the store. It caches the catalog pages, bypasses the cache for the cart and checkout paths, and purges product pages when the catalog changes. The result is measured by time to first byte on catalog pages and by the share of catalog requests that never reach the commerce platform. -This use case does not cover payment processing or inventory synchronization. +This use case does not cover protecting login and checkout against bots. --- @@ -192,12 +199,15 @@ This use case does not cover payment processing or inventory synchronization. | Requirement | Technical need | Product | Documented at | | --- | --- | --- | --- | -| Catalogue pages served fast under load | Cache identical responses on Azion's distributed network | Applications | [Cache settings](/en/documentation/build/cache/cache-settings/) | -| Cart stays personal | Bypass cache for authenticated paths | Applications | [Rules Engine](/en/documentation/platform/applications/rules-engine/) | -| Checkout resists abuse | Rate limit by client identity | Firewall | [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine/) | +| Catalog pages served fast under load | A cache setting on the application, matched on the catalog path | Cache | [Cache settings](/en/documentation/build/cache/cache-settings/) | +| Cart and checkout stay dynamic | A Bypass Cache rule on the application, matched by path and cookie | Application Accelerator | [Rules Engine](/en/documentation/platform/applications/rules-engine/) | +| Product pages refresh when the catalog changes | A purge by URL when a product changes | Cache | [Real-Time Purge](/en/documentation/build/cache/real-time-purge/) | +| Product images at the right size | Image Processor enabled for the application | Image Processor | [Image Processor](/en/documentation/build/image-processor/) | ``` -Each row names a business requirement, translates it into a technical need, and points at the page that documents it. The reader can check every claim before running a single step. +Each row names a requirement, the resource the reader configures, the Product that meets it, and the page that documents it. The reader can check every claim before running a single step. + +Application Accelerator is not among the catalog entry's Products. The Rules Engine reference confirms that the **Bypass Cache** behavior requires it, so the row carries it and the gap goes back to the catalog. ## Related diff --git a/src/content/docs/en/pages/style-guide/conventions/bilingual.mdx b/src/content/docs/en/pages/style-guide/conventions/bilingual.mdx index b27292c9ce..32e5ac0919 100644 --- a/src/content/docs/en/pages/style-guide/conventions/bilingual.mdx +++ b/src/content/docs/en/pages/style-guide/conventions/bilingual.mdx @@ -69,7 +69,7 @@ Five rules cover most of the work on a 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 product names: **Applications**, **Functions**, **Firewall**, **Azion Platform**, **Azion Marketplace**. -- Apply the substitutions: `aplicação`, not `aplicativo`; `rede distribuída`, not `borda`; `performance`, not `desempenho`. +- Apply the substitutions: `aplicação`, not `aplicativo`; `rede distribuída`, not `borda`, when translating existing text; `performance`, not `desempenho`. New 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]`. An English label on a Portuguese page is a visible defect. diff --git a/src/content/docs/en/pages/style-guide/formatting/headings.mdx b/src/content/docs/en/pages/style-guide/formatting/headings.mdx index 1b1acf2320..2bdedd69bb 100644 --- a/src/content/docs/en/pages/style-guide/formatting/headings.mdx +++ b/src/content/docs/en/pages/style-guide/formatting/headings.mdx @@ -63,6 +63,12 @@ A heading may carry a well-established acronym, as long as the first line below [Word choice](/en/documentation/style-guide/writing/word-choice/) holds the expansion rule for the rest of the page. +## Write code in a heading as plain text + +A heading carries no inline code. An error string, a command, or an identifier in a heading keeps its own spelling and casing and loses the backticks: `403 Forbidden on legitimate requests`, not `` `403 Forbidden` on legitimate requests ``. Backticks render a bordered code chip with a copy control, which breaks the heading line and follows the heading into the table of contents. A heading is a label, not a thing to copy. + +Two mechanics follow. A string that ends in a period loses it, because a heading carries no end punctuation. A bare `` in a heading is parsed as a tag and fails the build, so name what it stands for instead. + ## Keep emojis out of titles No emojis in titles, headings, or sidebar labels. Emojis break search indexing, read poorly in screen readers, and render inconsistently across platforms. diff --git a/src/content/docs/en/pages/style-guide/formatting/text.mdx b/src/content/docs/en/pages/style-guide/formatting/text.mdx index a70805ee5d..a76892b17e 100644 --- a/src/content/docs/en/pages/style-guide/formatting/text.mdx +++ b/src/content/docs/en/pages/style-guide/formatting/text.mdx @@ -73,7 +73,7 @@ Links inside a paragraph point at documentation pages. External links gather at ## Link the first mention of another documented element -When the prose names a product, a module, or a feature that has its own page, the first mention on the page links to that page: `Cache is an [Applications](/en/documentation/platform/applications/) module.` Later mentions stay plain, or bold where the product-name rule asks for it. +When the prose names a product, a platform resource, or a feature that has its own page, the first mention on the page links to that page: `Configure a [firewall](/en/documentation/platform/firewall/) to protect the application.` Later mentions stay plain, or bold where the product-name rule asks for it. The link replaces the bold at that first mention, because the text inside a link is never bold. A reader who meets an unfamiliar name always has its page one click away. diff --git a/src/content/docs/en/pages/style-guide/index.mdx b/src/content/docs/en/pages/style-guide/index.mdx index 99e0299972..43cef24114 100644 --- a/src/content/docs/en/pages/style-guide/index.mdx +++ b/src/content/docs/en/pages/style-guide/index.mdx @@ -16,7 +16,7 @@ This guide describes how Azion writes its documentation. Use it when you write a - [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/): the sentence rules, adapted from ASD-STE100. - [Procedures](/en/documentation/style-guide/writing/procedures/): the step grammar every numbered procedure follows. - [Word choice](/en/documentation/style-guide/writing/word-choice/): the vocabulary to avoid and the padding patterns to cut. -- [Documentation terminology](/en/documentation/style-guide/writing/terminology/): product names and translation rules. +- [Documentation terminology](/en/documentation/style-guide/writing/terminology/): product names, the four platform terms, and translation rules. - [Headings](/en/documentation/style-guide/formatting/headings/), [text formatting](/en/documentation/style-guide/formatting/text/), [code](/en/documentation/style-guide/formatting/code/), [punctuation](/en/documentation/style-guide/formatting/punctuation/), and [numbers and units](/en/documentation/style-guide/formatting/numbers/): how content is formatted. - [Content structure](/en/documentation/style-guide/content/choose-a-content-type/): the page kinds and how to pick one, including [quickstarts](/en/documentation/style-guide/content/quickstart/) and [use cases](/en/documentation/style-guide/content/use-cases/). - [Information architecture](/en/documentation/style-guide/content/information-architecture/): the thirteen slots a product section can fill, in the order the reader meets them. diff --git a/src/content/docs/en/pages/style-guide/writing/accessibility.mdx b/src/content/docs/en/pages/style-guide/writing/accessibility.mdx index e51a50808a..b4e40e5841 100644 --- a/src/content/docs/en/pages/style-guide/writing/accessibility.mdx +++ b/src/content/docs/en/pages/style-guide/writing/accessibility.mdx @@ -49,7 +49,7 @@ Do not open with "image of" or "picture of": the screen reader already announces - Incorrect: `![Screenshot](/assets/docs/images/uploads/request-flow.png)` - Incorrect: `![edge, cache, CDN, request flow, caching](/assets/docs/images/uploads/request-flow.png)` -- Correct: `![Diagram of a request that flows from the client through Azion's distributed network to the origin](/assets/docs/images/uploads/request-flow.png)` +- Correct: `![Diagram of a request that flows from the client through Azion's distributed infrastructure to the origin](/assets/docs/images/uploads/request-flow.png)` ## Do not rely on color alone in diagrams diff --git a/src/content/docs/en/pages/style-guide/writing/terminology.mdx b/src/content/docs/en/pages/style-guide/writing/terminology.mdx index 05a507f144..60f6cffabf 100644 --- a/src/content/docs/en/pages/style-guide/writing/terminology.mdx +++ b/src/content/docs/en/pages/style-guide/writing/terminology.mdx @@ -1,8 +1,8 @@ --- title: Documentation terminology description: >- - Apply the naming rules: the documentation product names and the terms that - stay in English. + Apply the naming rules: the four platform terms, the documentation product + names, and the terms that stay in English. meta_tags: 'style guide, terminology, product names' namespace: documentation_style_guide_terminology permalink: /documentation/style-guide/writing/terminology/ @@ -16,26 +16,45 @@ When a marketing name differs from the documentation name, write the marketing n Azion renamed its products and platform resources over time. The old names still appear in old pages, URLs, and directory names, so they can look current. Treat these names as history, not as synonyms. -## Name a module as a product +## Name the resource the reader works on -**Applications**, **Firewall**, and **Connectors** are platform resources: capabilities of the platform itself. The modules of a resource are products. Name the product first, with the resource as context. +Azion describes what it offers with four terms. They are related concepts, not four levels of one hierarchy: a resource may or may not be a Product, and a feature can belong to the Platform or to a resource. -- Correct: `Web Application Firewall (WAF) is a Firewall module that inspects HTTP and HTTPS requests.` +| Term | Answers | Examples | +| --- | --- | --- | +| Platform | What is the integrated Azion experience? | Azion Platform, with Console, the API, and the CLI as its interfaces | +| Product | What offering does Azion take to market? | WAF, Cache, Functions, Object Storage | +| Platform Resource | What does the reader create or manage? | an application, a firewall, a connector, a function, a bucket | +| Feature | What can the reader do or turn on? | Tiered Cache, DNSSEC, custom firewall rules | + +A Product is a go-to-market decision, not a billing test: it does not have to be sold or metered on its own. A feature is always scoped, so state whether it applies to the Platform or to a resource. + +Documentation writes in the Platform Resource nomenclature: it names what the reader creates or manages, and it joins that resource to the Product with a verb. The Product name, in Title Case, appears where the page means the offering: the section title, the first mention, and the definition block of an Overview. + +**Applications**, **Firewall**, **Connectors**, **Workloads**, **Custom Pages**, and **Certificate Manager** are Platform Resource types, not products. The thing the reader creates is an instance, lowercase: an application, a firewall, a connector. + +- Correct: `Configure a firewall to protect the application.` +- Correct: `Web Application Firewall (WAF) 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.` + +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. *Modules* stays where the Console renders it, inside a click path: `In the **Modules** section, turn on Application Accelerator.` A JavaScript module, an ES module, and an API field such as `modules.application_accelerator` keep their names. + +Azion Console, the API, the CLI, and the Terraform Provider are the Platform's interfaces, not resources. A field or an option on a resource is a setting, not a feature. ## Give a plural-form name a singular verb -A product name names one product, whatever its form. Applications, Functions, and Connectors each take a singular verb: `Applications caches content`, `Functions runs your code` — never `Applications cache`. Portuguese agrees the same way: `Functions executa suas funções`, never `executam`. +A product name or a resource type 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`. Portuguese agrees the same way: `Functions executa suas funções`, never `executam`. ## Lowercase the thing the customer builds -A product name is capitalized. The thing a customer creates with it is a common noun, and it stays lowercase. +A product name and a resource type name are capitalized. The thing a customer creates with them is a common noun, and it stays lowercase. - Correct: `Use **Applications** to build your own applications.` -- Correct: `**Functions** runs your functions on Azion's distributed network.` +- Correct: `**Functions** runs your functions on Azion's distributed infrastructure.` - Incorrect: `Deploy your first Application.` -The distinction keeps the product name meaningful. A page that capitalizes both leaves the reader unable to tell the product from the object. +The distinction keeps the type name meaningful. A page that capitalizes both leaves the reader unable to tell the type from the instance. ## Keep historical names in historical documents @@ -51,4 +70,4 @@ These terms are generic technical vocabulary, not product names. They stay in En A translation creates a second name for a concept the reader already knows in English. The documentation uses one term for one concept, on every page. -The strings `edge` and `edge computing` also stay untranslated where they already appear. That is guidance for translation, not permission to use them. New text names Azion's distributed network instead. +The strings `edge` and `edge computing` also stay untranslated where they already appear. That is guidance for translation, not permission to use them. New text names Azion's distributed infrastructure instead. diff --git a/src/content/docs/en/pages/style-guide/writing/voice.mdx b/src/content/docs/en/pages/style-guide/writing/voice.mdx index 7e28647265..78bffa4a7a 100644 --- a/src/content/docs/en/pages/style-guide/writing/voice.mdx +++ b/src/content/docs/en/pages/style-guide/writing/voice.mdx @@ -19,8 +19,8 @@ Documentation speaks to the person who does the work. Second person keeps the re Describe product behavior in the simple present. The present states what the platform does every time, and that is the claim a reader acts on. -- Before: `Applications will cache content on Azion's distributed network.` -- After: `Applications caches content on Azion's distributed network.` +- Before: `Applications will cache content on Azion's distributed infrastructure.` +- After: `Applications caches content on Azion's distributed infrastructure.` [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/) owns the full tense rules, including the ban on tenses built with auxiliary verbs. @@ -42,7 +42,7 @@ A step is an instruction, so it starts with the verb: `Select **Save**.`, never Documentation describes behavior and limits. It does not sell, because the reader already chose the product. An adjective that claims quality gives the reader nothing to act on; a behavior and a limit do. - Before: `Applications offers powerful, flexible caching capabilities.` -- After: `Applications caches content on Azion's distributed network. The default TTL is 60 seconds.` +- After: `Applications caches content on Azion's distributed infrastructure. The default TTL is 60 seconds.` The rewrite replaces two adjectives with facts the reader can test. The vocabulary rules are in [Word choice](/en/documentation/style-guide/writing/word-choice/). diff --git a/src/content/docs/en/pages/style-guide/writing/word-choice.mdx b/src/content/docs/en/pages/style-guide/writing/word-choice.mdx index 210e31c7c4..5fe6c5cefa 100644 --- a/src/content/docs/en/pages/style-guide/writing/word-choice.mdx +++ b/src/content/docs/en/pages/style-guide/writing/word-choice.mdx @@ -28,7 +28,7 @@ The test is whether the word claims *quality* or describes *behavior*. "Robust s The same failure hides in framing phrases. Write "Use for" instead of "Perfect for" or "Essential for", and "Use when" instead of "Best for". State the action directly instead of "empowers you to", and drop "modern", "seamless", and "cutting-edge" as modifiers. - Before: `Applications offers powerful, seamless caching, perfect for modern e-commerce.` -- After: `Applications caches content on Azion's distributed network.` +- After: `Applications caches content on Azion's distributed infrastructure.` *Significance inflation* is the same failure aimed at a concept: a sentence about how important something is, in place of what it does. "Caching plays a crucial role in modern web performance" gives the reader nothing to act on. State what the thing does and what its limits are. @@ -50,8 +50,8 @@ Five patterns add words without adding information. Two sentences in a row that open with the same words, or that share the same grammatical shape, read as a template even when every fact in them is right: -- Before: `An edge node that holds a valid copy answers from cache. An edge node that holds no valid copy fetches the object from the origin.` -- After: `When a node holds a valid copy, it answers from cache. Otherwise the node fetches the object from the origin.` +- Before: `A data center that holds a valid copy answers from cache. A data center that holds no valid copy fetches the object from the origin.` +- After: `When a data center holds a valid copy, it answers from cache. Otherwise the data center fetches the object from the origin.` Three techniques break the pattern: lead with the condition rather than the subject; contrast with a connective such as `Otherwise` instead of naming the subject twice; and let one sentence carry two clauses when they are one thought. A paragraph whose sentences all run the same mid-length reads the same way, so vary the length and prefer short. @@ -86,7 +86,7 @@ Each interface action takes one verb, the same verb on every page: | enter | type in, input | | refer to | see, check out | -"Enable" and "disable" stay legitimate for describing state in prose: "When the module is enabled, requests pass through it." +"Enable" and "disable" stay legitimate for describing state in prose: "When WAF is enabled on the firewall, requests pass through it." Do not use directional language. Name the element instead, per [Accessibility](/en/documentation/style-guide/writing/accessibility/). @@ -117,7 +117,7 @@ A product name is a proper noun, so it takes no article. - Incorrect: `Access the Azion Console.` - Correct: `Access Azion Console.` -The article returns when a common noun follows the name, because the article then belongs to that noun: `The Application Accelerator module speeds up dynamic content.` +The article returns when a common noun follows the name, because the article then belongs to that noun: `The Object Storage bucket holds the build output.` ## Use American English spelling diff --git a/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx b/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx index 3b88134e79..02ec8ca5af 100644 --- a/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx +++ b/src/content/docs/pt-br/pages/guia-de-estilo/componentes.mdx @@ -145,8 +145,8 @@ Um diagrama é um fence de código `mermaid`, não uma imagem. O texto chega a u ````md ```mermaid flowchart LR - Client --> Edge[Edge node] - Edge --> Origin[Origin server] + Client --> DC[Azion data center] + DC --> Origin[Origin server] ``` ```` @@ -226,7 +226,7 @@ import DocItem from '@aziontech/webkit/doc-item' - Como um edge node decide o que guardar e por quanto tempo. + Como um data center decide o que guardar e por quanto tempo. Condições e comportamentos nas fases de requisição e resposta. @@ -274,7 +274,7 @@ Um termo no meio da prosa que mostra sua definição ao passar o mouse ou recebe ```mdx import DocTooltip from '@aziontech/webkit/doc-tooltip' -A cache key decide o que corresponde. +A cache key decide o que corresponde. ``` - `client:visible` é obrigatório; sem ele o termo renderiza e nunca abre. @@ -335,7 +335,7 @@ import GlossaryFilter from '~/components/GlossaryFilter.astro' | Termo | Definição | | --- | --- | -| cache key | O identificador que um edge node monta a partir de uma requisição para decidir se duas requisições correspondem ao mesmo objeto em cache. | +| cache key | O identificador que um data center monta a partir de uma requisição para decidir se duas requisições correspondem ao mesmo objeto em cache. | ``` diff --git a/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx b/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx index 10f237d0d1..463a5e14f7 100644 --- a/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx +++ b/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx @@ -16,12 +16,14 @@ Dois princípios organizam tudo. As seções seguem a ordem da jornada do leitor Toda seção de produto segue esta ordem. A tabela mostra o que cada slot contém e quando ele existe. +Um tipo de recurso da plataforma com seção própria (Applications, Firewall, Connectors, Workloads, Custom Pages, Certificate Manager) segue o mesmo esqueleto. A visão geral descreve o tipo de recurso, o quickstart cria a primeira instância, e Glossário, Pricing e Changelog são obrigatórios como em um produto. Os produtos habilitados no recurso mantêm seções próprias, e a seção do recurso os lista como links cruzados em um único grupo de mesmo tipo. + | Ordem | Slot | Obrigatório | Contém | | --- | --- | --- | --- | | 1 | Overview | Sim | A página raiz do produto: o que o produto é, o que ele faz, quando usar | | 2 | Quickstart | Sim | [Páginas de quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/): de não usar o produto ao menor resultado funcional | | 3 | Como funciona | Quando o produto precisa de explicação | [Páginas de conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/): o mecanismo, o custo, como escolher entre opções | -| 4 | Features e capacidades | Quando o produto tem superfícies próprias | As superfícies do próprio produto, como um rules engine, um cache ou uma API de runtime | +| 4 | Features | Quando o produto tem superfícies próprias | As superfícies do próprio produto, como um rules engine, um cache ou uma API de runtime | | 5 | Guias e tutoriais | Quando o produto tem tarefas | Um [hub de navegação](/pt-br/documentacao/guia-de-estilo/conteudo/hubs-de-navegacao/) que lista os [guias how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) e os [tutoriais](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/) | | 6 | Exemplos | Opcional | Código funcional que o leitor copia, agrupado por linguagem ou por tarefa | | 7 | Referência | Quando o produto tem configurações | [Páginas de referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/): campos, valores, padrões | @@ -47,7 +49,7 @@ Outras linhas podem se agrupar da mesma forma. Um grupo é um pai de menu, não 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. -Um produto com módulos repete o padrão um nível abaixo. Um módulo com superfície própria ganha uma subseção com o mesmo esqueleto, reduzido às partes de que precisa. +Uma feature com superfície própria repete o padrão um nível abaixo: Tiered Cache sob Cache, com o mesmo esqueleto reduzido às partes de que precisa. Um produto habilitado em um recurso da plataforma mantém uma seção própria. O Quickstart carrega a interface dentro da página. Um produto cujo primeiro uso passa por Azion Console, pela Azion CLI ou pela API mantém uma página e seleciona a interface com tabs, então o slot tem uma linha e uma URL. O slot se divide apenas quando as interfaces não podem compartilhar um esqueleto de etapas, e para um agente de IA, cujo caminho é conduzido por prompt e não compartilha etapa com os outros. Essas páginas ficam agrupadas sob Quickstart, com o Console primeiro; o grupo é um pai da barra lateral, não uma página. [Páginas de quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) tem o teste. @@ -59,7 +61,7 @@ A seção de onboarding de plataforma em `/documentation/get-started/` é outra - **Pricing 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. - **Nunca adicione um slot para completar o padrão**, e nunca mantenha um vazio como marcador. -- **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 e capacidades por superfície. O Quickstart cresce dentro da própria página, por tabs de interface, e se divide apenas quando as etapas não podem ser compartilhadas. +- **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 Quickstart cresce dentro da própria página, por tabs de interface, e se divide apenas quando as etapas não podem ser compartilhadas. - **Os treze nunca aumentam em número.** ## Pricing e limites @@ -78,8 +80,8 @@ Conteúdo que nenhum produto possui sozinho vive ao lado dos produtos, não dent - A página documenta um produto: entra na seção desse produto, no slot que o tipo de conteúdo indica. - A página explica a plataforma, contas ou billing: entra em Fundamentals. - A página diagnostica problemas de plataforma ou leva ao time de suporte: entra em Suporte. -- A página resolve um cenário de negócio do início ao fim: é um [caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/), e entra em Guias. -- A página mostra como produtos se combinam em um design: entra em Architectures. +- A página constrói um caso de uso do catálogo: é um [caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/), e entra em Guias, na área da solução da sua entrada. +- A página mostra uma arquitetura de referência do catálogo, como produtos e recursos da plataforma se combinam em um design: entra em Architectures, sob a sua solução. - A página reúne links de uma área: é um [hub de navegação](/pt-br/documentacao/guia-de-estilo/conteudo/hubs-de-navegacao/), e precisa de um público real antes de existir. Quando nenhuma seção serve, abra uma issue antes de criar uma. Uma seção nova muda a navegação para todos os leitores. diff --git a/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx b/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx index a6652029fe..d1c070130a 100644 --- a/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx +++ b/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura.mdx @@ -13,7 +13,7 @@ import DocItem from '@aziontech/webkit/doc-item' ## Propósito -Uma página de arquitetura mostra como vários produtos formam um design. O leitor quer entender o formato de uma solução antes de construí-la. +Uma página de arquitetura mostra uma arquitetura de referência do catálogo de casos de uso: como produtos e recursos da plataforma se combinam em um design. O leitor quer entender o formato do design antes de construí-lo. Ela aplica a forma base de **explicação**, a mesma de uma [página de conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/). A diferença é o assunto: uma página de conceito explica uma coisa, uma página de arquitetura explica como muitas coisas se encaixam. @@ -21,14 +21,15 @@ Ela aplica a forma base de **explicação**, a mesma de uma [página de conceito Escreva uma página de arquitetura quando: -- Uma solução precisa de mais de um produto, e a relação entre eles é o ponto. +- Um design precisa de mais de um produto ou recurso da plataforma, e a relação entre eles é o ponto. - O leitor precisa ver a ordem de uma requisição ou de um dataflow para entender o design. - Um guia fica redesenhando o mesmo sistema em texto corrido. Não escreva uma página de arquitetura quando: - O assunto é um produto ou uma ideia. Escreva uma [página de conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/). -- O leitor quer construir a coisa. Escreva um [guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/) e aponte para ele daqui. +- O leitor quer construir a coisa. Escreva a [página de caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/) que a constrói, ou um [guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/), e aponte para ela daqui. +- O catálogo não tem entrada para o design. Proponha o design ao catálogo de casos de uso primeiro; a página vem depois da entrada. - O design não pode ser desenhado. Um design que você não consegue desenhar é um design que você ainda não entende bem o suficiente para publicar. ## Registro @@ -37,14 +38,14 @@ Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é ## Estrutura -O título nomeia o design como um sintagma nominal: `Content delivery on a distributed network`. O parágrafo de abertura diz qual problema o design resolve e para quem. +O título é o nome da arquitetura de referência no catálogo, sem alteração, traduzido na página em português. Esse nome é um sintagma nominal que nomeia o sistema construído, como `Server-rendered headless CMS website`, nunca com o sufixo *Reference Architecture*. O parágrafo de abertura é o Resumo da entrada: qual problema o design resolve, e para quem. Ele nomeia o caso de uso que o design implementa, com link para a página de caso de uso quando ela existe. **Seções obrigatórias, nesta ordem** - **`## Diagrama de arquitetura`**: o diagrama como um bloco de código `mermaid`, e depois um parágrafo que o lê. - **`### Dataflow`**: um passo a passo numerado do que vai para onde, com no máximo seis itens. -- **`## Componentes`**: o que cada parte faz e por que está ali. -- **`## Implementação`**: links para os guias how-to, e apenas links. +- **`## Componentes`**: uma entrada por componente da entrada do catálogo, com o seu papel. Produtos entram pelo nome, recursos da plataforma em minúscula como instâncias, e features e integrações rotuladas como o catálogo as rotula. +- **`## Implementação`**: apenas links. A página de caso de uso entra aqui quando ela constrói este design, seguida dos guias e templates do Marketplace que implementam todo o design ou parte dele. Uma página de caso de uso que constrói um design irmão recebe o link no parágrafo de abertura, como o caso de uso que a arquitetura implementa, e não aqui. - **`## Recursos relacionados`**: a seção de fechamento, uma lista de `DocItem`, cada linha com sua razão. ## Template @@ -54,7 +55,7 @@ import FrameBox from '@aziontech/webkit/frame-box' import ItemList from '@aziontech/webkit/item-list' import DocItem from '@aziontech/webkit/doc-item' - + ## Diagrama de arquitetura @@ -78,7 +79,8 @@ flowchart LR ## Implementação -- []() - . +- []() - . +- []() - . ## Recursos relacionados @@ -95,41 +97,43 @@ flowchart LR - **O diagrama nunca fica sozinho.** O dataflow numerado carrega o significado, e ele permanece mesmo quando o diagrama é renderizado. - **Rotule cada nó e cada aresta com palavras**, e nunca dependa apenas de cor para carregar uma distinção. - **Nomeie cada componente e diga por que ele está ali.** Uma lista de nomes de produto é uma lista de peças. -- **Aponte para a implementação, não a coloque aqui.** Os passos vão em um [guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/). +- **Aponte para a implementação, não a coloque aqui.** Os passos vão na [página de caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/) ou em um [guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/). - **Escreva só as seções que você consegue confirmar.** Uma seção obrigatória cujo conteúdo você não consegue confirmar com o time que cuida do produto fica de fora até que consiga, nunca é preenchida com um palpite. +- **Informe o permalink quando a página é publicada**, para que o campo Docs da entrada do catálogo passe a Published. ## Exemplos -- [Implante sites Jamstack em uma rede distribuída](/pt-br/documentacao/arquiteturas/construir-e-executar-aplicacoes/implantacao-aplicacoes-jamstack/): um diagrama, um dataflow numerado, os componentes envolvidos e links para a implementação. +- [Implante sites Jamstack](/pt-br/documentacao/arquiteturas/construir-e-executar-aplicacoes/implantacao-aplicacoes-jamstack/): a página publicada que o catálogo liga a *Git-driven static website*. Ela traz um diagrama, um dataflow numerado, os componentes envolvidos e links para a implementação. -Este trecho, de uma página em inglês, mostra a abertura, a seção do diagrama e o dataflow: +Este trecho mostra a abertura, a seção do diagrama e o dataflow da página *Git-driven static website*. O catálogo registra essa arquitetura de referência sob o caso de uso *Build and run marketing websites*. Nenhuma página de caso de uso foi publicada ainda, então o caso de uso é nomeado sem link: ````mdx -This design delivers a site's content from locations close to users. It reduces latency and the load on the origin infrastructure. Use it when your team delivers static-heavy sites and applications. +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 *Build and run marketing websites*. -## Architecture diagram +## Diagrama de arquitetura ```mermaid flowchart LR - Client -->|HTTP request| Node[Nó da Azion] - Node --> Rules[Rules Engine] - Rules --> Cache[Cache layer] - Cache -->|Cache hit| Client - Cache -->|Cache miss| Origin[Origin server] - Origin --> Cache + Repo[Repositório Git] -->|push| App[Azion GitHub App] + App -->|resultado do build| Bucket[Bucket do Object Storage] + Client[Cliente] -->|requisição HTTP| DC[Data center da Azion] + DC --> Cache[Cache] + Cache -->|cache hit| Client + Cache -->|cache miss| Bucket + Bucket --> Cache ``` -O diagrama mostra o caminho de uma requisição e de sua resposta em uma aplicação na rede distribuída da Azion. A requisição do cliente chega a um node na rede distribuída da Azion, onde Rules Engine e a camada de cache a processam. O conteúdo que não está em cache vem do servidor de origem, e a resposta retorna ao cliente pelo mesmo node. +O diagrama carrega dois fluxos. O fluxo de publicação vai do repositório, pelo GitHub App, até o bucket, e só se move em um push. O fluxo de requisição vai do cliente a um data center na infraestrutura distribuída da Azion. Ali, o Cache responde com a sua cópia ou lê o arquivo no bucket. ### Dataflow -A request moves through the design in this order: +O conteúdo percorre o design nesta ordem: -1. Um cliente envia uma requisição HTTP ou HTTPS para um domínio associado a uma aplicação. -2. No node da Azion, Rules Engine processa a requisição. Ele aplica políticas de cache e comportamentos de otimização de imagem na fase de request. -3. A camada de cache avalia a requisição. Em uma correspondência de cache key, o node entrega o objeto a partir do cache. -4. Em um cache miss, o node encaminha a requisição ao servidor de origem. A origem responde, e o node armazena o conteúdo em cache. -5. Antes de a resposta retornar ao cliente, Rules Engine processa as políticas da fase de response. O node então entrega o conteúdo ao usuário. +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. +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. ```` ## Relacionados diff --git a/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/casos-de-uso.mdx b/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/casos-de-uso.mdx index fe63dab6bc..0c96df5278 100644 --- a/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/casos-de-uso.mdx +++ b/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/casos-de-uso.mdx @@ -1,7 +1,7 @@ --- title: Casos de uso description: >- - Escreva uma página de caso de uso: um cenário de negócio virando + Escreva uma página de caso de uso: um caso de uso do catálogo virando especificação executável, com produtos exigidos, arquitetura e resultados medidos. meta_tags: 'style guide, use cases, guides, spec driven documentation' @@ -14,16 +14,17 @@ import DocItem from '@aziontech/webkit/doc-item' ## Propósito -Uma página de caso de uso transforma um cenário de negócio em uma configuração que alguém consegue construir e verificar. O leitor chega com uma situação, não com uma tarefa: uma loja que fica lenta durante uma promoção, um evento ao vivo que precisa alcançar mais uma região. +Uma página de caso de uso transforma uma entrada do catálogo de casos de uso em uma configuração que alguém consegue construir e verificar. A entrada dá à página o título, o cenário, os produtos e as arquiteturas de referência que ela pode construir. A página nunca inventa um caso de uso próprio. O catálogo é mantido pela Azion. Quem precisa de uma entrada, ou encontra uma errada, pede antes de escrever a página. O pedido vai pelos templates de issue do repositório, ou pelo dono do catálogo dentro da Azion. O leitor chega com uma situação, não com uma tarefa: uma loja que fica lenta durante uma promoção, um evento ao vivo que precisa alcançar mais uma região. Um caso de uso é uma especificação, não um artigo. Ele carrega em uma página tudo de que o implementador precisa: os produtos que o cenário exige, a arquitetura, a configuração, as verificações e as métricas que mostram o resultado funcionando. Esse implementador muitas vezes é um agente, então a página é escrita para ser executada, não para ser lida. -Casos de uso vivem na seção Guias, nunca dentro de um produto. +Casos de uso vivem na seção Guias, nunca dentro de um produto, na área da solução da sua entrada no catálogo. O rótulo da área é o nome da solução. ## Quando usar **Reconheça um caso de uso por:** +- Um título que é o nome de um caso de uso do catálogo, sem alteração, traduzido na página em português: uma frase verbal no imperativo que nomeia um workload, sem nomes de produto. - Um leitor que chegou com uma situação de negócio, e não com uma tarefa. - Uma tabela de requisitos ligando cada necessidade de negócio ao produto que a atende. - Um resultado que continua mensurável depois que a configuração funciona. @@ -31,7 +32,7 @@ Casos de uso vivem na seção Guias, nunca dentro de um produto. **Continua sendo um caso de uso quando:** -- Configura quatro coisas ou menos. Mais de quatro significa que são dois casos de uso. +- Configura quatro coisas ou menos. Mais de quatro significa que a entrada é larga demais para uma página. - Aponta para o procedimento genérico em vez de repeti-lo aqui. - É publicado sem demo, porque nenhuma existe. Nunca descreva uma demo que não roda. @@ -39,7 +40,7 @@ Casos de uso vivem na seção Guias, nunca dentro de um produto. - Não há nada a configurar. A página explica um design, então escreva uma [página de arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura/). - A configuração é uma tarefa só. Isso é um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/). -- O objetivo é técnico e não precisa de enquadramento de negócio. Isso é um [guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/). +- O catálogo não tem entrada para ele, e o objetivo não precisa de uma situação de cliente. Isso é um [guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/). Uma entrada faz da página um caso de uso, qualquer que seja a redação do objetivo. - O leitor não tem cenário, só o produto. Isso é um [tutorial](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/). ## Registro @@ -50,11 +51,11 @@ Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo **Componentes obrigatórios** -- **Cenário**: três a cinco frases nomeando o que o time tem, o que ele precisa e o que esta página configura. Seguidas de uma linha declarando o que o caso de uso não cobre. +- **Cenário**: três a cinco frases tiradas do Cenário da entrada do catálogo. Elas nomeiam o ator, o workload e a situação em que ele está, o que esta página configura e o resultado mensurável. Seguidas de uma linha declarando o que o caso de uso não cobre, a exclusão da própria entrada. - **Pré-requisitos**: uma seção `## Pré-requisitos`, cada item um link ou um comando de uma linha quando existe um. -- **Produtos exigidos**: a tabela de requisitos. Uma linha por requisito, nomeando a necessidade técnica, o produto que a atende e a página que a documenta. -- **Arquitetura de referência**: uma seção `## Arquitetura de referência` com um diagrama em `mermaid` e um `### Fluxo de dados` numerado abaixo dele. -- **Configuração**: uma seção `## Configure ` por requisito, no máximo quatro, cada uma com um procedimento que termina com sua frase de resultado. +- **Produtos exigidos**: a tabela de requisitos. Uma linha por requisito, nomeando a necessidade técnica, o produto que a atende e a página que a documenta. A coluna Produto contém os produtos da entrada do catálogo. Uma dependência que a documentação do produto confirma e a entrada omite também entra na tabela, e a lacuna é informada ao catálogo. A necessidade técnica nomeia o recurso da plataforma que o leitor configura. +- **Arquitetura de referência**: uma seção `## Arquitetura de referência`. Ela abre nomeando qual das arquiteturas de referência da entrada esta página constrói, e depois traz um diagrama em `mermaid` e um `### Fluxo de dados` numerado. As outras arquiteturas de referência da entrada viram links para páginas de arquitetura, quando existem. +- **Configuração**: uma seção `## Configure ` por requisito cuja configuração é específica deste caso de uso, no máximo quatro. Cada uma tem um procedimento que termina com sua frase de resultado. Um requisito atendido por um procedimento genérico não ganha seção. A tabela de requisitos aponta o guia que o documenta, e a checagem fica na seção de verificação. - **Verificação**: uma seção `## Verifique a configuração` com uma checagem por requisito e o resultado esperado. - **Medição de resultados**: uma seção `## Medindo resultados` nomeando as métricas que mostram a configuração funcionando, e onde ler cada uma. - **Best practices**: uma seção `## Best practices` com as recomendações e o raciocínio por trás de cada uma. @@ -80,10 +81,12 @@ Copie o template e substitua cada ``: import DocCardGroup from '@aziontech/webkit/doc-card-group' import DocCard from '@aziontech/webkit/doc-card' - + - + ## Pré-requisitos @@ -101,6 +104,8 @@ precisa e o que esta página configura.> ## Arquitetura de referência + + ```mermaid flowchart LR @@ -166,25 +171,27 @@ Para : - **Escreva uma especificação, não um artigo.** Todo valor é concreto, todo comando roda, e nenhum passo diz "dependendo da sua configuração". O leitor pode ser um agente, e um agente não resolve uma ambiguidade perguntando. - **Mostre o output depois de cada comando.** O leitor vê como o sucesso se parece antes que o próximo passo dependa dele. A regra está em [Procedimentos](/pt-br/documentacao/guia-de-estilo/escrita/procedimentos/). -- **Reduza o cenário a uma configuração construível.** Declare assim: `Um