20 lines
1.6 KiB
ReStructuredText
20 lines
1.6 KiB
ReStructuredText
|
|
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's 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.
|
|
|
|
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.
|