Start with the subject and then provide supporting context; don't bury the lead. Don't spend two or three paragraphs justifying the topic before mentioning it.

Do not: All feedback starts with an interaction between a business unit and a person. These persons are called "customers".

Recommended: Customers are the people who interact with business units and who provide feedback about the unit.

Get to the point of an action, and be concise. Avoid you can, in order to, etc.

Do not: You can use Slicer™ in order to create bread slices of equal thickness, from the same loaf.

Recommended: Use Slicer™ to create two equal bread slices.

Write like a person talking, not static or robotic. Read your text out loud? Does it sound like a person: like you? Be friendly, but don't over due casual speech. The text should have a "rhythm" when read out loud.

Do not: Slice the bread. Make a sandwich.

Do not: First you must slice the bread. Next, take bread slices you just created and put them together to make a tasty sandwich.

Recommended: Start your sandwich by slicing the bread, then use the slices to create a perfect sandwich.

Do not make future claims about features or products except where preparations are required by the reader.

Do not: A new feature will be available in the next release.

When a feature is scheduled to be deprecated or removed in a future release, best practice is to use the shared warning note in the global warehouse:

When it is known that a change is coming that will affect the functionality of the current system, it is OK to include a Note or warning to that affect. Avoid saying when it will happen unless there need for preparation. For example:

Use unordered lists unless there is a sequence to be followed, or when there is a need to enumerate list items.

Avoid stating how many items are in the list.

Do not use: The three new items are:

Recommended: The new items are:

Use em-dash (not colons):

• Thing 1 — the first new item.
• Thing B — the second new item.

For more information about working with lists, see Lists.

Shorter is better. Most readers will scan the text. Removed words like that or in order when they add nothing to the comprehension.

Do not: In order to create a perfect sandwich, it is important that you to start with two slices of bread.

Better: To create a perfect sandwich, it is important you to start with two slices of bread.

Recommended: To create a perfect sandwich, start with two slices of bread.

Use sentence-style capitalization except when absolutely necessary to match a UI element. (And work with the team to get the UI changed if appropriate.)