-
Notifications
You must be signed in to change notification settings - Fork 8
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
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 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.
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.
Azion rule:
- Don't underline. Only automatic underlining while using 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.
Azion rules:
- Use code blocks to highlight code.
- Commands, codes, and flags: add ` between items. Example:
-
azioncli build,print (name), the-yflag enforces standard responses.
-
- 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).
Azion rules:
-
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.
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 the table title, each column header, and texts in cells.
Check also Headings capitalization.
Azion rules:
- Use contractions to be conversational. Example: It's the final step/NOT It is the final step.
- Avoid contractions with verbs + nouns. Example: Browser is/ NOT Browser's.
- Use contractions 'nt ('don't').
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 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 personal pronouns and an eventual wrong use of them.
It also helps to avoid gender bias.
Azion rule:
- Avoid using We, I, us, our, my, mine, and prioritize using the company's name when necessary. Example: Azion Support Team, not Our Support Team.
- Don't use Latin abbreviations (e.g., i.e.).
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)'."
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.
Azion rules:
- Write directly, clearly, and with a touch of familiarity.
- Try to keep sentences short (< 30 words).
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.
Avoid using colons in a title or heading.
Don't use end punctuation in headings.
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
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.
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:
- On the File menu, select Open database.
- In Username, enter your name.
- In Password, enter your password > select OK.
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.
- 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."
Azion rule:
- No spaces. First letter after a bar in lower case (exception: proper names). Example: 100 km/hr, ⅕
Azion rules:
- Use colons when introducing a list (:), then capitalize at the beginning of the list.
- Use lowercase after a colon (:) in texts.
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.
In general, don't use ellipses.
Azion rules:
- Avoid using them on Azion properties (.com emails, in product).
- Limit their use in personal communication with customers.
Azion rule:
- Hyphens (-) connect two words that modify a noun and don’t have a space (real-time logging).
- 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.
Always use the Oxford comma in English.
In Portuguese, there's no Oxford comma rule.
Azion rule:
- Immediately follow the number, no spaces. Example: 100%
Azion rule:
- En dashes (–) support a range of time or quantities and don’t have a space (50–70%).
See also Dashes.
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:
-
- Clique no botão Abrir; a janela Open File é apresentada. 2. Defina um nome para a sua aplicação; por exemplo, my-web-app.
-
- 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.
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.
Azion rule:
- Don't use &.
- Spell out numbers zero through nine, and use numerals for 10+.
Azion rule:
-
In English: use periods for decimals and commas to separate numbers over 100. Example:
- 10,000 or 25,456,990
- 9.5 or 3.14159
-
In English: add a zero before the decimal point. Example: 0.25
-
In Portuguese (BR): use commas for decimals and periods to separate numbers over 100. Example:
- 10.000 or 25.456.990
- 9,5 or 3,14159
-
In Portuguese (BR): add a zero before the decimal comma. Example: 0,25
Azion rule:
- Mind the difference between writing units in English and Brazilian Portuguese. Example:
- 2,000 requests (EN)
- 2.000 requisições (PT-BR)
- 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. Example: 5 GB of storage, 15-inch screen.
- Use abbreviations only with numbers in specific measurements, such as 20 MP, and don't follow the abbreviation with a period.
- For texts in Brazilian Portuguese, insert a space between the unit and the numeral and write the units in lowercase.
Azion rule:
- Dates are written in order of month-day-year with bars, but prioritize using the full name of the month.
- Example: 1/7/2022 or January 7, 2022
- Days and months should be capitalized in English. Days and months shouldn't be capitalized in Brazilian Portuguese.
MS rules:
- Don't use ordinal numbers for dates.
- Always spell out the name of the month.
Azion rule:
- The dollar sign goes before the number. Example: $1,000
- For texts in Brazilian Portuguese, use Real (R$) before the number, with space. Example: R$ 1.000
- 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
Use en dash, not a hyphen.
Don't add -ly to an ordinal number.
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.
- 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.
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).