Top Rules Azion Style Guide

As mentioned in the Style Guide Overview, we researched and got inspiration from some of the existing technical style guides and glossaries associated with our industry. However, we created our own definitions and rules to align with Azion's general guidelines, as well as our internal definitions created from experience.

Prioritizing style guides:

• Azion general guidelines
• Azion Product Education team Style Guide (this document)
• Microsoft Style Guide
• Google Developer Style Guide

---

Typographic

• Bold

Azion rules:

• Use bold for keywords, never whole sentences.

• Don't use bold in links.

• Requirement(s)/Requisito(s): format Requirement(s)/Requisito(s) in bold and add the requirement in the same line or you can list items with bullets or numbers. Example:

  • Requisito: antes de criar uma aplicação você deve (ou precisa) instalar o framework Frame.
  • Requisitos: antes de criar uma function você deve: * Instalar o Node.js. * Instanciar um projeto.

• Name of programming languages and frameworks: use bold with the term "linguagem de programação <nome_da_linguagem>"

  • The code is written in the programming language JavaScript.

• File names:

  • The names.txt file contains a list of names.

• Use bold to indicate UI elements, configurations, and products. For products, only the first time the term appears in each section or heading.

• Don't use bold for third-party names, products, elements, etc.

• Italic

Azion rules:

• Use italics to draw attention. Example:

  • By activating Slice, the current cache key will be ignored and a new cache key will be formed.

• User-entered data. This rule doesn't apply to commands in the CLI or API interfaces. Example:

  • Choose a name for your edge function, such as my-first-function.

• Underline

Azion rule:

• Don't underline. Only automatic underlining while using links.

• Code Format

Azion rules:

• Use code blocks to highlight code.
• Commands, codes, and flags: Add ` between items. Example:
  • azioncli build, print (name), the -y flag enforces standard responses.

---

Language and Grammar

General tip:

• Lead with your objective.

MS Style Guide recommends making every word count. Concise, clear sentences save space, are easy to understand, and facilitate scanning. Use simple words with precise meanings, and remove words that don’t add substance. Avoid wordiness, adverbs, and complex words.

• In general, don't use "the" with products. Example: Access Real-Time Manager. NOT Access the Real-Time Manager.
• If there's a complement to the product's name, such as "Application Acceleration module", "the" should be used. Example: The Application Acceleration module speeds up web applications and APIs.

Azion recommendations:

• Write directly, clearly, and with a touch of familiarity.
• Use American English unless you’re sending something personalized to someone in the UK/Europe. For example: “Organize” not “organise”.

MS Style Guide recommends trying to keep writing suited to an international audience by using simple terms that can work across cultures (no culturally specific idioms).

• Acronyms

Azion rule:

• Acronyms should be preceded by definition/complete name when used for the first time. Example:
  • Two-Factor Authentication (2FA).

Some exceptions can apply to common terms related to Azion or the technology market. Example: - IP address, WAF.

• Capitalization

Azion rules:

• Capitalize proper nouns (nouns that refer to a specific person, place, object, or location), including Azion's products and platform.
• Instances of products that customers create with our products aren't capitalized. Example: Customers use Edge Application to build their edge applications. // Edge Functions allows you to build edge functions on Azion.
• Titles: use sentence-style capitalization. Exceptions: proper names, including Azion brand and products.
• URLs and namespaces: always use lowercase capitalization.
• Tables: use sentence-style capitalization for table title, each column header, and texts in cells.

Check also Headings capitalization.

• Contractions

Azion rules:

• Use contractions like "I'm" instead of "I am" to be conversational.

• Avoid contractions with verbs + nouns (Browser is/ NOT Browser's)

• Use contractions 'nt ('don't')

• Grammatical Person

  Grammatical person: Customer as reader

Azion rules:

We address the customer (addressee) using the second-person singular: you. Even though our documents may impact dozens or hundreds of people, we're speaking to the one person who is reading them. When our writing reflects this, it’s more economical and has a greater impact.

Pronouns help the readers picture themselves in the doc and relate to what we’re saying. More than any other single technique, using “you” pulls users into the information and makes it relevant to them. When we use “you” to address users, they're more likely to understand what their responsibility is.

For our usual technical documentation, the guideline is to use “YOU”, when referring to the customer and “IT” when referring to one of our products. This will help to avoid the personal pronouns and an eventual wrong use of them.

It also helps to avoid gender bias.

**Grammatical person: Azion as writer**

Azion rule:

• Avoid using We, I, us, our, my, mine, and prioritize using the company's name when necessary.

• Foreign terminology

• Don't use Latin abbreviations (e.g., i.e.).

• Gender and gender bias

Avoid, as long as possible, using gender explicit pronouns in English as well (He, She, Her, Him) and, instead, use the neutral pronoun “They” whenever the genre of the person to whom you’re writing is irrelevant.

Additionally, the MS Style guide recommends avoiding gender bias related to roles, professions and similar. Example: "Consider using 'camera operator(s)' instead of 'camera(?:m[ae]n|wom[ae]n)'."

• Passive voice

Throughout the text, we should always prioritize the active voice, because it gives a broader sense of responsibility and focuses on the action (verb) that is to occur, instead of the subject (noun). Passive voice sentences often use more words, can be vague, and can lead to a tangle of prepositional phrases. Also, the use of singular nouns and verbs prevents confusion about whether a requirement applies to an individual or several groups.

Examples:

• Active: The candidate believes that Congress must place a ceiling on the budget.

• Passive: It is believed by the candidate that a ceiling must be placed on the budget by Congress.

• Sentence length

Azion rules:

• Write directly, clearly, and with a touch of familiarity.

MS recommendation:

• Try to keep sentences short (< 30 words).

• Units

Azion rule:

• Mind the difference between writing units in English and Brazilian Portuguese. Example:
  • 2,000 requests (EN)
  • 2.000 requisições (PT-BR)

MS recommendation:

• Use numerals for measurements of distance, temperature, volume, size, weight, pixels, points, and so on—even if the number is less than 10.
• Add a zero before the decimal point for decimal fractions less than one.
• Insert a space between the unit of measure and the numeral, or hyphenate if the measurement modifies a noun.
• Use abbreviations only with numbers in specific measurements, such as 20 MP, and don't follow the abbreviation with a period.

---

Headings

• Heading acronyms

We can use consolidated acronyms in the titles, but it's still worth writing in full on the first line and then the acronym.

See also Acronyms.

• Heading colons

Avoid using colons in a title or heading.

• Heading punctuation

Don't use end punctuation in headings.

• Heading capitalization

Use sentence-style capitalization. Exceptions: proper names, including Azion brand and products.

Examples:

• How to configure Advanced Cache Key for Edge Application
• How to customize an error response page

---

Lists

• Bulleted lists

Use a bulleted list for things that have something in common but don’t need to appear in a particular order. Example:

The database owner can:

• Create and delete a database.

• Add, delete, or modify a document.

• Add, delete, or modify any information in the database.

• Numbering lists

Use a numbered list for sequential items (like a procedure) or prioritized items (like a top 10 list). Example:

To sign on to a database:

1. On the File menu, select Open database.
2. In Username, enter your name.
3. In Password, enter your password > select OK.

• Punctuating lists

Lists, whether numbered, in bullets, or inside tables, have specific punctuation rules. The most common rule we use is to end items in a list with more than three words with a full stop (.).

See Microsoft Lists - Punctuation for full details and scenarios.

• Tables

• In cells, overall, don't use a full stop at the end of the item.

MS rule: "For the text in cells, use periods or other end punctuation only if the cells contain complete sentences or a mixture of fragments and sentences."

---

Punctuation

• Bars

Azion rule:

• No spaces. Example: 100 km/hr, ⅕

• Colons

Azion rules:

• Use colons when introducing a list (:), then capitalize at the beginning of the list.

• Use lowercase after a colon (:) in texts.

• Dashes

Azion rules:

• Em dashes (—) connect two thoughts or provide emphasis and don’t have a space on either side.

Pro tip: the shortcut to em dash is Shift+Option+Hyphen on a Mac and alt+0151 on Windows.

• En dashes (–) support a range of time or quantities and don’t have a space (50–70%).

In Portuguese, dashes have spaces to separate them from the main sentence on both sides. Avoid using dashes according to the context.

• Ellipses

In general, don't use ellipses.

• Exclamation Points

Azion rules:

• Avoid using them on Azion properties (.com emails, in product).

• Limit their use in personal communication with customers.

• Hyphens

Azion rule:

• Hyphens (-) connect two words that modify a noun and don’t have a space (real-time logging).

MS rule:

• In general, don’t hyphenate words beginning with auto-, such as autoscale and autodial, unless it's necessary to avoid confusion. When in doubt, check The American Heritage Dictionary.

• Oxford comma

Always use the Oxford comma in English.

In Portuguese, there's no Oxford comma rule.

• Percentages

Azion rule:

• Immediately follow the number, no spaces. Example: 100%

• Ranges

Azion rule:

• En dashes (–) support a range of time or quantities and don’t have a space (50–70%).

See also Dashes.

• Semicolon

Azion rule:

• To describe a result and an example of the steps of a procedure. Put the action, a semicolon, and then the result or example. Example:
  • 1. Clique no botão Abrir; a janela Open File é apresentada. 2. Defina um nome para a sua aplicação; por exemplo, my-web-app.

MS rule:

• Avoid colons to "simplify sentences". We can use it as a reminder to review the context and confirm if it's the exception mentioned above.

• Periods

Azion rules:

• Don't use periods after titles and headings.

• Don't use periods at the end of URLs.

• For periods in tables, check the [Tables] section.

• Others

Azion rule:

• Don't use &.

---

Numbers

General tips:

• Spell out numbers zero through nine, and use numerals for 10+.

Azion rule:

• Use periods for decimals and commas to separate numbers over 100 (in English). Example:

  • 10,000 or 25,456,990
  • 9.5 or 3.14159

• Dates

Azion rule:

• Dates are written in order of month-day-year.
  • Example: 1/7/2022 or January 7, 2022

MS rules:

• Don't use ordinal numbers for dates.

• Always spell out the name of the month.

• Currency

Azion rule:

The dollar sign goes before the number. Example: $1,000

• Time

MS recommendations:

• Don't use 24/7. Use all day, every day, always, or something similar.

• AM, PM: use AM and PM (preceded by a space). Use capital letters for AM and PM. Example: 10:45 AM / 6:30 PM

• Negative numbers

Use en dash, not a hyphen.

• Ordinal

Don't add -ly to an ordinal number.

• Cross-links

• If a new term appears within the product, link the item to the respective documentation.

• Don't use bold in links.

• Avoid linking short words. It helps accessibility to link longer words.

---

Procedures

Azion rules:

• Start a step-by-step with a sentence. Example:
  • To set up an API key, follow these steps:
• Use numerals to indicate each step (1. , 2. ,...)
  • When writing in Portuguese, avoid using defined articles on foreign words, such as “Plataforma de Edge Computing” or “Configurações de Cache Settings”. When necessary, see the Glossary.

---

Markdown conventions

• To add italics, use *. Example: word
• To add lists, use -. Example:
  • First information.
  • Second information.
• Always add a dividing line (---) between sections of a documentation.
• Add a blank line at the end of each markdown file.
• To add Azion Docs links, add the link starting from /en or /pt-br.
• Try to keep your markdown files pretty by using proper formatting.

---

Brand content

Azion rules:

• If a new term appears within the product, link the item to the respective documentation.
• Capitalize words when referring to Azion's products (Edge Computing, Edge Application).