📄️ 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.
Style
Learn the key elements of style, tone, and grammar for user documentation.
🗃️ Accessible and inclusive language
4 items
📄️ Active and passive voice
Active voice is generally better than passive voice because it is shorter, clearer, and more modern. Readers mentally convert passive voice to active voice, which takes more effort.
📄️ Past, present, and future tense
Write in present tense, not past or future.
📄️ First, second, and third person
Address the reader directly by writing in second person.
🗃️ Pronouns
3 items
📄️ Contractions
Use common contractions to enhance the friendly and conversational tone of your content.
📄️ -ing words (gerunds, present participles)
Both gerunds and present participles are verbs (action words) that end in -ing; for example, “running.” They have slightly different uses in practice, but this section refers to both as -ing words.
📄️ Plurals and possessives
The use of plurals and possessives can make documentation harder for users to understand. Whenever possible, use the following guidance to avoid plurals and possessives.
📄️ Modifiers
Place modifier words like "only" or "not" immediately before the phrase that they modify.
📄️ Jargon
Technical writing must always be clear, concise, and accessible for those not familiar with technical shorthand.
📄️ Initialisms and acronyms
An initialism is an abbreviation made from the initials of a phrase. For example, AR (augmented reality), VFX (visual effects), DLC (downloadable content).
📄️ Capitalization
Avoid unnecessary capitalization. Too much capitalization is distracting because it's hard for the reader to understand whether they have missed some information. Make sure the context is clear so that the user can understand whether you are referring to a generic or Unity-specific understanding of the term.
📄️ Links and citations
Follow these guidelines when you add links and citations to your documentation.
🗃️ Numbers, measurements, and equations
7 items
🗃️ Punctuation
3 items
🗃️ Documenting feature lifecycle stages
2 items
🗃️ Writing about third-party platforms and products
2 items