Voice Style

The essence of the Ansible writing style is short sentences that flow naturally together. Mix up sentence structures. Vary sentence subjects. Address the reader directly. Ask a question. And when the reader adjusts to the pace of shorter sentences, write a longer one.

Write how real people speak…
…but try to avoid slang and colloquialisms that might not translate well into other languages.
Say big things with small words.
Be direct. Tell the reader exactly what you want them to do.
Be honest.
Short sentences show confidence.
Grammar rules are meant to be bent, but only if the reader knows you are doing this.
Choose words with fewer syllables for faster reading and better understanding.
Think of copy as one-on-one conversations rather than as a speech. It is more difficult to ignore someone who is speaking to you directly.
When possible, start task-oriented sentences (those that direct a user to do something) with action words. For example: Find software… Contact support… Install the media…. and so forth. Use imperative mood for procedure steps (“Run the command”). You can use “you” in general instructional text when it fits naturally.

Active Voice

Use the active voice (“Start Linuxconf by typing…”) rather than passive (“Linuxconf can be started by typing…”) whenever possible. Active voice makes for more lively, interesting reading. Also avoid future tense (or using the term “will”) whenever possible For example, future tense (“The screen will display…”) does not read as well as an active voice (“The screen displays”). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.

Sentence length

Aim for 32 words or fewer per sentence. Varying sentence length improves readability, but most sentences should stay concise.

Precise verbs

Prefer precise, specific verbs over weak verbs such as “is”, “are”, “occur”, or “happen.” Where possible, start sentences with a real subject instead of expletive constructions such as “There is”, “There are”, or “It is.”

Prefer single-word verbs

Where a single-word verb exists, prefer it over a phrasal verb. For example, write “click the button” rather than “click on the button”, and “omit the parameter” rather than “leave out the parameter.”

Avoid terms of politeness

Do not use “please”, “thank you”, “kindly”, or similar terms of politeness in technical content. Use direct imperative instructions instead. For example, write “Configure the inventory file before running the playbook” rather than “Please configure the inventory file before running the playbook.”

Avoid anthropomorphism

Do not assign human qualities to software or components. Describe what the user does or what happens, not what the software “thinks”, “knows”, “wants”, or “decides.” For example, write “The module returns a list of packages to install” rather than “The module knows which packages to install.”