Style Guide: Quick Reference

Follow the Open 3D Engine (O3DE) Docs Style Guide in your documentation. This ensures that the documentation is consistent and helpful to users.

Write for accessibilityDocumentation is written in U.S. English. Use simple and precise words wherever possible. Write short and complete sentences. Break up information into smaller bodies of text.
Voice and toneUse active voice and present-tense verbs wherever possible. Write simply, respectfully, and professionally.

Refer to the user as “you”. Refer to the O3DE software, O3DE community, or O3D Foundation as “we”.
O3DE terminologyUse O3DE-specific terms as defined in the terminology page. Update the terminology page if you introduce new terms.
Standard domain and industry terminologyUse terminology that is standard in the domain or industry. If there’s ambiguity, include additional context to make sure the reader understands the meaning.
Terms to avoidAim for inclusivity in your choice of words.
Acronyms, abbreviations, and Latin phrasesWrite acronyms or abbreviations in their expanded form first, followed by the acronym in parentheses. Don’t abbreviate common words or use Latin phrases; use the complete word or a similar one.
Idioms, slang, colloquialisms, or jargonDon’t use them. These words and phrases may be understood by native U.S. English speakers, but are difficult to translate.
Hugo and MarkdownDocumentation is written in Markdown (.md) files and built by Hugo , a static site generator. It’s primarily formatted using Markdown syntax , with support for in-line HTML. Additional content formatting includes images, videos, callout boxes, math equations, and diagrams. Callout boxes are implemented through shortcodes. Math equations can be rendered using MathJax formatting. Diagrams can be rendered using Mermaid syntax inside Markdown code blocks.
MetadataDocumentation must comply with metadata requirements, including linktitle, title, and description. Use weight to override the default alphabetical sort order.
Topic headingsSection titles must use H2 (##) headings. Subsection titles follow as H3 (###) and H4 (####) headings. Topic headings must use sentence case. The H1(#) heading is reserved for the page title which is specified in the topic’s metadata.
User interface, inputs, and hotkeysBold all instances.
Files, directories, and pathsUse code-style formatting. Provide context on what a path is relative to. When applicable, link to the file in the o3de repository .
Applications, tools, Gems, and componentsBold only the first on-page occurrence. Subsequent occurrences on the same page remain unformatted.
Code, commands, and API objectsUse code-style formatting for commands and API objects. Use code blocks for multiple lines of code.
TerminologyBe consistent in the use of terms. Italicize new terms, and follow with a definition. Terms that are unique to O3DE must be included in the Terminology page.
Trademark terminologyProperly format trademark titles and terminology according to its use from the source. Provide a link to the source’s relevant material.
Additional content
ImagesStatic images must be .png format. Diagrams must be .svg format.
Animated imagesUse short videos to demonstrate a feature’s functionality. Prefer to use .mp4 files that are less than 512 KB. Videos must not exceed 1 MB in size. Use of .gif format is deprecated and no longer permitted.