Version:

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.

Language
Write for accessibility	Documentation 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 tone	Use 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 terminology	Use O3DE-specific terms as defined in the terminology page. Update the terminology page if you introduce new terms.
Standard domain and industry terminology	Use 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 avoid	Aim for inclusivity in your choice of words.
Acronyms, abbreviations, and Latin phrases	Write 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 jargon	Don’t use them. These words and phrases may be understood by native U.S. English speakers, but are difficult to translate.
Formatting
Hugo and Markdown	Documentation 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.
Metadata	Documentation must comply with metadata requirements, including linktitle, title, and description. Use weight to override the default alphabetical sort order.
Topic headings	Section 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 hotkeys	Bold all instances.
Files, directories, and paths	Use `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 components	Bold only the first on-page occurrence. Subsequent occurrences on the same page remain unformatted.
Code, commands, and API objects	Use `code-style` formatting for commands and API objects. Use code blocks for multiple lines of code.
Terminology	Be 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 terminology	Properly format trademark titles and terminology according to its use from the source. Provide a link to the source’s relevant material.
Additional content
Images	Static images must be `.png` format. Diagrams must be `.svg` format.
Animated images	Use 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.