Top 10 Unity style tips
Understand the most important style aspects of writing documentation and access resources for more in-depth information.
Unity style is based on industry best practices, with specific guidance that fits Unity needs.
- Document the current state of the product.
- Use US English spelling and punctuation.
- Write in present tense.
- Address the reader directly.
- Start with the most important information.
- Use short, simple sentences.
- Avoid ambiguities.
- Use consistent terminology and capitalization.
- Use consistent formatting.
- Write for a diverse global audience.
This primer covers the most important parts of writing style for documentation at Unity. It's by no means exhaustive.
If you have a question or situation that's not covered in this primer, then check if another area of the Unity Style Guide covers your issue. If your question isn't covered or you have other feedback about the Style Guide, contact the #unity-style-guide Slack channel.
Document the current state of the product
Focus on how the product works right now. If you document a change in behavior, don't compare it with previous behavior or assume that readers are familiar with the previous state of the product.
Don't mention upcoming features or planned updates, or compare current functionality to upcoming functionality.
Avoid using time-sensitive words like "new" or "currently." Time-sensitive documentation requires more maintenance, because it can become outdated or misleading when the mentioned functionality is added or unscheduled.
Deprecation notices are the only exception to this rule. For deprecation notices, it's necessary to mention the future state where the functionality isn't available. Follow Unity's standard guidelines for deprecating APIs and other Unity features and products.
For more information about time-sensitive documentation, refer to the Unity Style Guide guidance on Current and future states of the product.
Use US English spelling and punctuation
Use US English spelling and punctuation in all text, including API names, UI strings, and console messages.
For a spelling reference, consult the Merriam-Webster online dictionary.
New API names must use US English spelling conventions.
note
If you're documenting an existing API that uses British English spelling, then use the British spelling only when writing the API name itself. In surrounding text, use US spelling.
For example, discussion of the MonoBehaviour class might look as follows:
- The
MonoBehaviourclass provides lifecycle functions that determine the specific behavior of objects in your scripts.
Write in present tense
Write in simple present tense in all documentation, procedures, UI strings, and console messages. Present tense is preferred because it's simple and reflects the user performing actions in the current moment.
Don't use past or future tense to describe user behavior or the way the product works.
In some specific cases, such as release notes or console messages, using past tense might be appropriate to describe something that happened in the past. Minimize the use of past tense as much as possible, using it only when the use of present tense might be confusing or misleading. Use simple past tense to make it clear that it refers to a completed action, not an ongoing action.
Address the reader directly
Write as though you're speaking directly to the user. Use a friendly, respectful, and human tone.
Focus on actions that the user needs to take, or information that they need to understand their task. Use the personal pronouns "you" or "your" where necessary for explanations or instructions. Make it clear when the user needs to perform an action.
Use the imperative tone for direct instructions. Most documentation takes the form of instructions or information addressed directly to the user.
Make sure that you keep a specific audience in mind when you write documentation. It's important that the tone and expertise level of the content remains consistent on any given page.
Start with the most important information
Don't make the reader work any harder than necessary to understand your content. Always lead with the most important information for the situation. This principle applies at the page, paragraph, and sentence level.
Write the circumstances, conditions, or goals that the content applies to up front. Before going into depth with instructions or details, help the reader identify whether this content applies to them and their goals.
Use short, simple sentences
Keep your writing brief and to the point. Aim to keep sentences under 25 words in length.
Limit each sentence to one thought or action. Don't chain several ideas together into one sentences with colons, semi-colons, or dashes. Instead, separate each idea into its own, simple sentence.
In tasks, write one precise action per sequential step.
Avoid ambiguities
Make the documentation as clear and understandable as possible. While topics and details might be complex, your writing must be simple and straightforward. Readers must be able to follow your meaning on a first read.
Be explicit with your instructions. Use active voice as much as possible.
Be careful with pronouns and make sure that it's clear what you're referring to.
Don't use conditional words such as "could," "would," "should," or "may." These words can lead to ambiguity about the specific requirements or actions that the reader must take. Instead, use precise language that clearly states expected actions and outcomes. In rare cases, when an outcome is genuinely uncertain, you can use "might."
For words with multiple meanings, make sure that you stick to a single definition within your content.
If you have the time, it's good practice to read through your work the next day. It's easier to identify any ambiguities when you review the content after a break.
Use consistent terminology and capitalization
Maintain consistency across documentation and other Unity content. Consistency helps readers understand quickly and improves the quality of translated content.
As much as possible, use the same terminology as in the product and other related content. Spell out abbreviations and acronyms, and define them where necessary.
Use consistent capitalization. Capitalize only when referring to product names, UI windows and views, components and their properties, or UI labels with capitalization. Very few Unity-specfic terms require capitalization. Check the terminology list to be sure, and when in doubt, don't capitalize.
If you're working on an area that uses specific terminology, contact the Style Guide maintainers to add your terms and usage to the guidance.
Use consistent formatting
Follow the text formatting guidelines to make sure that readers can understand when you're discussing an API element, a UI element, or a general term.
Write API names and code-related text in monospaced font. Use code blocks for longer code samples. Use consistent code conventions in code examples and user-accessible code samples.
Use bold font to write names of UI elements, controls, and UI labels. For specific guidance on formatting for instructions, refer to User interactions.
Don't use italic or underlined font in documentation content. These styles can be confusing to readers because they often have multiple meanings and inconsistent usage.
For more formatting guidelines, including how to format titles and headings, refer to the formatting section of the Style Guide.
Write for a diverse global audience
Unity products have global reach and users have a variety of different backgrounds. Unity content must be as accessible as possible and respectful of the reader and their experiences.
Follow the Unity inclusive language guidelines. Avoid slang, jargon, and metaphors that some users might not understand.
Be mindful that many readers have English as a non-primary language. Complex or ambiguous content can be hard for these readers to understand, and it costs more to translate. To reduce complexity, be careful with pronouns and modifiers, and use inclusive language.