Writing tips
Content that’s easy to read tends to be easy to localize and translate. If you follow the writing recommendations in this style guide, you’re off to a great start. Pay particular attention to:
Tips for all global content
These practices will help localizers and customers.
Write short, simple sentences. Punctuating a sentence with more than a few commas and end punctuation usually indicates a complex sentence. Consider rewriting it or breaking it into multiple sentences.
Replace complex sentences and paragraphs with lists and tables.
Include that and who. They help to clarify the sentence structure.
Examples
Inspect the database to verify that all tables, data, and relationships were correctly migrated.
Select the checkbox of each folder that you want to sync with your desktop.
Include articles, such as the. Articles help readers and translation software identify the nouns and modifiers in a sentence.
Examples
Empty the container.
The empty container
If necessary for clarity, include verbs in short headings and UI labels. For example, say Access is denied instead of Access denied.
Use sentence-style capitalization. Capitalize proper nouns only, including trademarks and the names of products.
Avoid idioms, colloquial expressions, and culture-specific references. They can be confusing for non-native English speakers and hard to localize. Consider the worldwide implications of what you write. Customers in other locales may not know much about the history and culture of your country.
Avoid modifier stacks. Long chains of modifying words are confusing even to native English speakers. For example, say "Your migration will proceed more smoothly if you have a project plan that's well thought out," not "With an extremely well thought-out Windows migration project plan, your migration will go more smoothly."
Use active voice and indicative mood most of the time. Use imperative mood in procedures.
Keep adjectives and adverbs close to the words they modify. Pay particular attention to the placement of only.
Avoid linking more than three phrases or clauses by using coordinate conjunctions such as and, or, or but. Better yet, avoid linking more than two.
Additional tips for machine translation
Writing style affects the quality of machine translation. These tips will help you write text that's more likely to be translated accurately by machine translation. Follow these guidelines for technical content, instructions, white papers, and other content that has high business value but won't be localized.
Use conventional English grammar and punctuation. Try to balance a friendly voice with clear, accurate English.
Use simple sentence structures. Write sentences that use standard word order (that is, subject + verb + object) whenever possible.
Use one word for a concept, and use it consistently. Avoid using synonyms to refer to the same concept or feature. And don’t use the same word to refer to multiple concepts or features.
Limit your use of sentence fragments. Sentence fragments can be hard to translate.
Use words ending in –ing carefully. A word ending in –ing can be a verb, an adjective, or a noun. Use the sentence structure and optional words to clarify the role of the –ing word.
Use words ending in –ed carefully. A word ending in -ed can be a modifier or part of a verb phrase. Use the sentence structure and optional words to clarify the role of the –ed word.
Add a determiner (a, an, the, this) before or after the –ed word.
Example
They have an added functionality.Add a form of the verb be.
Example
Configure limits for the backup that are based on the amount of storage space available.Split the sentence in two.
Example
Configure limits for the backup. These limits should be based on the amount of storage space available.Rewrite the sentence to avoid the –ed word.
Example
Configure limits for the backup. Base the limits on the amount of storage space available.
Use only common abbreviations, such as USB, and abbreviations that are defined in glossaries. Check with a localization expert to find out if an acronym is defined.