Skip to main content

Tone and audience

When you write for external users, make sure that your language is casual yet professional, and aimed at users of all skill levels.

The Unity documentation (the User Manual and API Reference) is a reference guide for Unity users. The best way to describe the documentation is as a wiki for the Unity Editor and Services, maintained by the Documentation team. It's not a tutorial section, and it's not a blogging platform.

The Unity tone of voice is professional and conversational, with the primary goal of being clear, concise, and accessible. This conversational tone means that it's okay to use features of natural speech, such as the following:

  • Contractions, for example "isn't," "haven't," "you're" (refer to Microsoft: Use contractions)
  • Prepositions at the end of sentences, for example "the project to open the asset with," rather than "the project with which to open the asset" (refer to Microsoft: Prepositions)

Use your own judgment to make sure the language and tone you use doesn't get in the way of giving clear information and instruction.

Audience​

One of Unity’s key principles is democratization: making development available to everybody. Unity documentation is accessible to users of all skill levels and doesn't make assumptions about the reader’s level of knowledge.

Unity documentation has the following two main areas with slightly different target audiences:

  • User Manual: A wide target audience of programmers, artists, designers and project managers at all skill levels.
  • API reference: Programmers are the primary target audience. It's still important to remember that programmers of all skill levels use the API reference, so keep it clear and easy to follow.

Communication for all skill levels​

A user turns to the documentation when they don't know something. Be specific and logical about information, even if it seems obvious from your perspective.

Avoid phrases like "use common sense." Additionally, avoid phrases like "and so on" or "etc." at the end of sentences. This indicates an assumption that the reader already understands the material, and can make the reader feel out of their depth.