Repository navigation
docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages - #2558
Open
marcus-souza-azion wants to merge 29 commits into
Open
marcus-souza-azion wants to merge 29 commits into
marcus-souza-azion wants to merge 29 commits into
Conversation
The request path diagram drew six unconnected nodes inside a data center subgraph, so it rendered tiny and showed neither the workload nor the way back. It now follows the use-case convention: top to bottom, the workload first, dotted return arrows, numbered labels that match the steps under it. Also rewords the opening sentence, the Our Network link (the page does not list data centers), the standalone resources table row, and the What you can build intro, in English and Portuguese. Also moves the custom page set from the Application row to the Workload row, because the workload deployment names it, and phrases the Standalone resources row like the other rows.
… topology list Replaces the two opening paragraphs with a short definition of Azion, states plainly that each product lives inside the resource it acts on, drops the card instruction the diagram does not need, and rewrites the application and functions items without diagram jargon. Adds a sign-up button next to the account paragraph, in English and Portuguese. Also says that a Reseller account, not a Group account, holds client accounts, as the Console account menu shows.
…arn about frameworks The GitHub path named controls the import form no longer has (build and deploy commands, Protect with Azion Firewall, Create and deploy). Its last steps now follow the Import from GitHub form: Application Name, Preset, Root Directory, Install Command, Deploy, and the Creation failed state with the Deploy Log panel. Also points the template path at Astro Boilerplate while keeping the choice open, makes the supported-framework requirement a warning with the Preset list and a compatibility link, renames the Test it headings, replaces the AI prompt, links the sign-up page, drops the unsourced credit-card claim, and points the custom-domain card at the guide that does it, in English and Portuguese. The step that set Root Directory and Install Command becomes one step per field, the link to the GitHub import guide uses its current title, and the Portuguese related resources no longer say edge.
Splits the email-change sentences into their own paragraph, moves the 30-day Activity History retention into a note, names Account Owners and the Company ID as the Console does, and sets the Group account type in italics, in English and Portuguese. Also follows the Console where the page disagreed with it: Reseller accounts create client accounts and Company accounts create Group accounts, the Apartment, floor, etc. address field is optional, and the account owner changes the login settings. Most permissions, not all, come in View and Edit pairs, because the Orchestrator permissions have Edit without View.
The Console splits the old Account Profile into General and Company Information, calls the legal identifier Company ID, adds an optional Apartment, floor, etc. address field, and has a GitHub Integration section before account deletion. The page now follows that, and drops Company Size and Job function, which the Console no longer shows, in English and Portuguese. Also names the Login Settings and Danger Zone sections as the Console does, rewrites the opening that listed the sections, and moves the headings to sentence case.
…to Profile The Console names the section Profile. English and Portuguese.
…s management Uses Azion Web Platform where the page meant the platform, and renames the User profile section to Profile, as the Console does. English and Portuguese. Also names the Phone Number field and documents the Status section with its Active switch, as the Console user form shows them.
…and clients Adds a Group accounts section: Company accounts create Group accounts in Groups Management, with the same sections as a client account. The page is renamed Groups and clients, so the sidebar no longer reads Accounts > Accounts, and the links to it follow the new title. Reorders the Accounts group of the Fundamentals sidebar: Your settings, Account settings, Activity history, then Groups and clients, which only some account types use. English and Portuguese. Also aligns the page with the Console account types: Company accounts create Group accounts in Groups Management, and Reseller accounts create Client accounts in Clients Management. The page said that Clients belong to Group accounts; its description, note, and client fields now follow the Console, including the Apartment, floor, etc. address field.
…ent plans The page still described a sign-up credit and a 365-day trial period. It now describes the Hobby, Pro, and Enterprise plans as the pricing page states them: included usage and limits, what happens above them on each plan, the Pro billing cycle, and when plan changes take effect. English and Portuguese. Also names Savings Plans as the pricing page does.
…ough the API only Azion Console has no screen for the policy; every guide sets it through /v4/auth/policies/lockout. English and Portuguese.
…gh the API only Azion Console has no screen for the policy; the guide sets it through /v4/auth/policies/session. English and Portuguese.
…e permissions API Compared the table with GET /v4/iam/permissions. Renames the four rows the API now names differently (View Analytics, View and Edit Workloads, View Events, View and Edit DNS) and adds the 32 permissions the table did not list: Connectors, Custom Pages, Storage Credentials, Policies, VCS Integrations, VCS Continuous Deployment, Orchestrator Nodes and Services, Marketplace Publisher, and SCIM Integration. The API returns names only, so each new row states what its name says, plus the matching View requirement on Edit rows. English and Portuguese. Also states the Edit Multi-Factor Authentication row by its name only, says that the Clients feature belongs to Reseller accounts, and names Certificate Manager in the Portuguese table.
…irect-loop steps The 500 fix named API v3 Console controls (an Origins tab, Protocol Policy, Enforce HTTP). The connector now carries the setting as Transport Protocol Policy, with Force HTTP, so both procedures follow the current Console and use DocSteps. Each status code is now its own section with its fixes under it, the error page fields are a table, the request examples are text fences, and the page closes with related resources. The Portuguese page gains the redirect-loop fix it was missing. Each procedure ends with the state it leaves, and the opening no longer says Below.
…g and related resources Renames the Error treatment section to Common MFA problems and closes the page with the MFA guide and the three settings pages that turn MFA on. English and Portuguese. For a lost phone, the page now says that an Account Owner resets the MFA, or Azion Support when you are the only owner, and links the sign-in troubleshooting page.
Replaces the closing 'visit the creating an account page' sentence with a related-resources list (create an account, the Social Login switch in Account settings, Single Sign-On) and uses dash bullets. English and Portuguese.
The creation fields become a table with a Required column, the visibility rules get their own section, and the page closes with related resources. The English title moves to sentence case, and the Portuguese page now names the last modified date, as the English page does. The page now opens with what a personal token is, the English description says what the Portuguese one says, and the Personal Token menu option is named as the Console names it.
…uides The five one-paragraph sections that defined IdP, service provider, SAML, OIDC, and SCIM become one terms table, and the Implementation table of guides becomes the related-resources list. The X.509 section keeps its own heading, in sentence case. English and Portuguese. The page now links the Azion Console setup guide for SSO.
The three settings become one table with their API fields, types, and defaults from the configuration guide. The Implementation table and the three mid-page guide buttons become inline links and a related-resources list. English and Portuguese. The Unlocking users heading becomes Manual unlock.
The two settings become one table with their API fields, ranges, and defaults from the configuration guide; their sections keep the definitions and the update behavior. The Implementation table and the guide button become an inline link and a related-resources list, and the Session time heading now names Maximum session time. English and Portuguese. The maximum idle time range now states its 1440-minute ceiling, as the configuration guide does.
Each FAQ question becomes a subject heading under Attestation details, with its answer unchanged, and the page closes with related resources. The English title moves to sentence case, and the Portuguese page now names PCI DSS 4.0.1, as the English page does. Both descriptions now say 4.0.1, the coverage sentence names each Platform Resource without calling any of them an add-on, and the Portuguese related resource says SOC 2 Tipo 2.
Each FAQ question becomes a subject heading under Report details, with its answer unchanged, and the page closes with related resources. The English title moves to sentence case, and a Portuguese heading typo is fixed (availação). The coverage sentences name each Platform Resource without calling any of them an add-on, the SOC 2 Type 2 heading matches the body, and the Portuguese page says Azion Web Platform instead of plataforma de edge.
The diagram was an image of a two-column table that still named the Azion Edge Platform. It is now a table with the same rows, readable in both languages and by agents reading the markdown twin, and the page text names Azion Platform throughout. Also moves the title and headings to sentence case, turns the bold Azion Control Assurance line into a heading, fixes the description and the opening that started with "This document", and closes the page with related resources. English and Portuguese. The description now starts with a verb, and the page says Azion Platform where it said Azion's Platform.
…rces to four Related resources had seven items, above the cap of four. The five Fundamentals pages the body already links leave the list, and the teams and users how-to guides join MFA and Single Sign-On. English and Portuguese.
The Profile, Contact information, and Security settings bullets become field tables, with a Required column where the page states it, and the page closes with related resources. The title and the Contact information heading move to sentence case. English and Portuguese. Portuguese also fixes the platforma typo, names Social Login as the product, and writes e-mail.
The General, Company information, and Address information bullets become field tables, the Social Login and MFA links move to related resources, and the title moves to sentence case. English and Portuguese. Portuguese also drops Atualmente, fixes usuário to usuários, and removes the empty separator at the end of the file.
The page gains related resources and a sentence-case title. English and Portuguese. The Portuguese description said the history goes back to account creation, which contradicted the 30-day limit in the body; it now matches the English one. The empty separator at the end of the Portuguese file is removed.
The Main settings, Address information, and Account Owner bullets become field tables, the subsection headings move to sentence case, and the page closes with related resources. The required fields stay as the page states them: marked with an asterisk in the form. English and Portuguese.
… related resources The table headers become Permission and Description, the Account Owner restriction becomes a note, Error treatment becomes Errors, and the page closes with related resources. The title moves to sentence case. English and Portuguese. Row fixes: View Functions named no object in English and said domains in Portuguese; Wildcard Purge spelled Real Time-Purge, with a broken bold in Portuguese. Portuguese also fixes Ele concede, platforma, Listas de Rede, and times.
The Profile, Contact information, Security settings, and Status bullets become field tables; the Account owner and Teams rows absorb the paragraphs that followed them, and the page closes with related resources. The title moves to sentence case. English and Portuguese. English fixes privilegies and teams already existent; Portuguese drops eficientemente and facilmente and uses equipes for teams.
This was referenced Nov 5, 2026
marcus-souza-azion
marked this pull request as ready for review
November 11, 2026 19:41
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Related issue: MM-16289. The source is a reader review of the Fundamentals pages, one highlight per sentence, read on the Portuguese pages.
Pages affected: 21 pages, each in
enandpt-br, plussrc/nav/trees/fundamentals.json. Theenpermalinks, all under/en/documentation/fundamentals/:/(the Fundamentals overview),how-it-works/,first-deploy/accounts-teams-and-users/,your-settings/,account-settings/,activity-history/,accounts/,teams-permissions/,users-management/,billing-and-subscriptions/multi-factor-authentication/,single-sign-on/,social-login/,personal-tokens/,account-lockout-policy/,user-session-timeout/,pci-dss-certification/,soc/,shared-responsibility/http-status-codes/The Fundamentals pages are the first pages a new reader opens. A review read them as a reader would and marked 42 sentences: some were hard to follow, some named Console controls that no longer exist, some carried facts that are no longer true, and one diagram could not be read. This PR applies that review in both languages, then applies the same kind of check to the HTTP status codes page and to every page of the Security group, and brings those pages, and every page of the Management group, to the structure the style guide sets.
Where the facts come from
GET /v4/iam/permissions. The public OpenAPI file has no IAM paths, so nothing states what each new permission grants beyond its name.X-Azion-Edge-Locationis always present,X-Azion-Edge-Popcomes only withPragma: azion-debug-cache, and the default error page for a 400 shows the fields the page lists.Type of change
feat)fix) — typo, broken link, wrong informationdocs) — rewrite, expansion, upkeepi18n)refactor/chore) — reviewed by UXE, no content mixed inAuthor checklist
type(scope): summary(see GOVERNANCE.md §4)title,description,meta_tags,namespace,permalink,last_reviewedpt-brupdated in this PR or follow-upi18nissue created:pnpm build:local(build + frontmatter check) without errors