Version:

Icon of a magnifying glass.
  Edit on GitHub

IN THIS ARTICLE

O3DE Documentation Contribution Style Guide

Ready to contribute to the Open 3D Engine (O3DE) documentation? This style guide prepares you with recommendations and guidelines for submitting a docs pull request. We’ve tried to provide contributors with all the information that they need about writing style, formatting, and the conventions used across our docs site. If you need guidance that isn’t included, file an issue with the D&C SIG to suggest an improvement.

Following the style guide is the best way to make sure that contributions to the O3DE docs get reviewed and merged quickly. We don’t expect every contributor to know every detail. All we ask is that contributors be familiar with the guide and follow it to the best of their ability. Pull request reviews are there to catch any of the most serious style errors in contributions.

Ideal traits

What are the ideal traits for O3DE docs?

  • ✅ Descriptive active voice - Do descriptive sentences have a clear subject and action verb?
  • ✅ Answer the question at hand - Does the documentation answer a what, why, how, or where type of question?
  • ✅ Help the user - Does the documentation show the user something meaningful?
  • ✅ Consistency - Does the content consistently follow the style guide?

What’s in the guide?

  • Quick Reference - A quick reference of common style guide rules.
  • Writing Guidelines - Guidance on our documentation style, tone, and how to write in an accessible manner.
  • Formatting Guidelines - Specific rules regarding formatting and typesetting our documentation, such as how to format executable names, file paths, and code blocks. Covers the features available in the variant of Markdown that the O3DE docs site uses.
  • Formatting Tools - A list of the tools that can assist with the specialized formatting needs of some O3DE documentation.
  • Metadata - Details on the available (and required) Hugo front matter metadata to use in the YAML headers of Markdown files.
  • Shortcodes - The Hugo shortcodes that we use for the O3DE docs. Includes call-out boxes, version numbers, static paths that O3DE uses, and other useful tidbits.
  • Submitting Media - Guidelines for submitting media (images, video, audio, or assets) to the docs.

This guide isn’t meant to be an extensive introduction to either Markdown or the Hugo site generator . If you’re learning Hugo, refer to Work with Hugo.