3. Basic Rules¶

3.1. Use Standard American English¶

Ansible has customers/users all around the globe, but the headquarters is in Durham, NC, in the US. Use Standard American English rather than other variations of the English language.

3.2. Write for a Global Audience¶

The idea behind global writing is that everything you say should be understandable by those of many different backgrounds and cultures. References, therefore, should be as universal as possible. Avoid idioms and regionalism and maintain a neutral tone that cannot be misinterpreted. Avoid attempts at humor.

3.3. Follow Naming Conventions¶

Always follow naming conventions and trademarks. If you aren’t sure how a product should be properly referred to, ask the Engineering Product Manager of that product line (ansible-core or Tower) for information.

3.4. Important Information First¶

Important information stated at the beginning of a sentence makes it easier to understand.

Unclear: The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety.

Clearer: Danger! Stay away from cliff.

3.5. Sentence Structure¶

Good sentence structure helps convey information. Try to keep the most important information towards the beginning of the sentence.

Bad: Furthermore, large volumes of water are also required for the process of extraction.

Better: Extraction also requires large volumes of water.

3.6. Avoid padding¶

When reading a piece of technical writing, the audience does not benefit from elaborate prose. They just need information on how to perform a task. Avoid using padding, or filler. Don’t use phrases such as, kind of, sort of, and essentially.

3.7. Avoid redundant prepositional phrases¶

Prepositional phrases, the combination of a preposition with a noun phrase, are among the worst offenders in making text long and tiresome to read. Often, it is possible to replace an entire phrase with a single word.

Use now instead of at this point in time. Use suddenly instead of all of the sudden.

3.8. Avoid verbosity¶

Write short, succinct sentences. Never say, “…as has been said before,” “..each and every,” “…point in time,” etc. Avoid “…in order to,” especially at the beginning of sentences. Every word must contribute meaning to the sentence. Technical writing is information delivery.

3.9. Avoid pomposity¶

While it is good to have a wide vocabulary, technical writing is not the place for showing off linguistic abilities. Technical writing is about producing clear, plain instructions for a specific audience.

3.10. Action verbs, menus, and commands¶

We interact with computers in a variety of ways. You can select anything on an application user interface by selecting it using a keyboard or mouse. It is important to use action verbs and software terminology correctly.

The most frequent verbs used in software are:

Click
Double-click
Select
Type
Press

Use of an action verb in a sentence (bolded words):

In the dialog box, click Open.
Type a name in the text box.
On the keyboard press Enter.

Use of menu actions and commands in a sentence:

On the File menu, click Open.
Type a name in the User Name field.
In the Open dialog box, click Save.
On the computer keyboard, press Enter.
On the toolbar, click the Open File icon.

Make users aware of where they are in the application. If there is more than one method to perform an action, use the most common method. Define “what, where, and how” in each step of the task or procedure. Describe menu items for the current task left to right, top-down.