openstack/openstack-manuals
Code Issues Proposed changes

Merge "Contributor Guide: Fix markup"

Browse Source
This commit is contained in:
Jenkins 2015-10-29 12:37:33 +00:00 committed by Gerrit Code Review
commit 88e1e3431d
1 changed files with 11 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/contributor-guide/source/writing-style/general-writing-guidelines.rst
View File

@ -119,7 +119,7 @@ Write in second person
---------------------- ----------------------
Users are more engaged with documentation when you use second person (that is, Users are more engaged with documentation when you use second person (that is,
you address the user as `you`). you address the user as "you").
Writing in second person has the following advantages: Writing in second person has the following advantages:
@ -135,17 +135,17 @@ Writing in second person has the following advantages:
Use first person plural pronouns (we, our) judiciously. These pronouns Use first person plural pronouns (we, our) judiciously. These pronouns
emphasize the writer or OpenStack rather than the user, so before you use emphasize the writer or OpenStack rather than the user, so before you use
them, consider whether second person or imperative mood is more them, consider whether second person or imperative mood is more
"user-friendly." However, use `we recommend` rather than `it is recommended` "user-friendly." However, use "we recommend" rather than "it is recommended"
or `OpenStack recommends`. or "OpenStack recommends".
Also, you can use `we` in the place of OpenStack if necessary. Also, you can use "we" in the place of OpenStack if necessary.
Do not use first person to avoid naming the product or to avoid using passive Do not use first person to avoid naming the product or to avoid using passive
voice. If the product is performing the action, use third person (the product voice. If the product is performing the action, use third person (the product
as an actor). If you want to de-emphasize the agent of action and emphasize the as an actor). If you want to de-emphasize the agent of action and emphasize the
object on which the action is performed, use passive voice. object on which the action is performed, use passive voice.
The first-person singular pronoun `I` is acceptable in the question part of The first-person singular pronoun "I" is acceptable in the question part of
FAQs and when authors of blogs or signed articles are describing their own FAQs and when authors of blogs or signed articles are describing their own
actions or opinions. actions or opinions.
@ -214,7 +214,7 @@ Describe the most common use case first
Put the most common case in the main clause and at the beginning of a Put the most common case in the main clause and at the beginning of a
paragraph or section. You can introduce additional paragraph or section. You can introduce additional
use cases by starting a sentence with `however` or `if`. use cases by starting a sentence with "however" or "if".
Do not humanize inanimate objects Do not humanize inanimate objects
--------------------------------- ---------------------------------
@ -244,7 +244,7 @@ Try to avoid the following words as much as possible:
+------------------------+----------------------------------+ +------------------------+----------------------------------+
| catastrophic | serious | | catastrophic | serious |
+------------------------+----------------------------------+ +------------------------+----------------------------------+
| bad | Use `serious` or add explanation | | bad | Use "serious" or add explanation |
+------------------------+----------------------------------+ +------------------------+----------------------------------+
| fail | unable to | | fail | unable to |
+------------------------+----------------------------------+ +------------------------+----------------------------------+
@ -312,8 +312,8 @@ after the pronoun.
Do not split infinitives Do not split infinitives
------------------------ ------------------------
Do not place modifiers between `to` and the verb. Typically, placing Do not place modifiers between "to" and the verb. Typically, placing
an adverb or an adjective between `to` and a verb adds ambiguity to an adverb or an adjective between "to" and a verb adds ambiguity to
a sentence. a sentence.
However, in some cases it is acceptable. However, in some cases it is acceptable.
@ -326,7 +326,7 @@ Avoid personification
--------------------- ---------------------
Do not express your fears or feelings in technical writing. Avoid Do not express your fears or feelings in technical writing. Avoid
the adverbs such as `probably`, `hopefully`, `basically`, and so on. the adverbs such as "probably", "hopefully", "basically", and so on.
Do not use contractions Do not use contractions
----------------------- -----------------------
@ -346,4 +346,4 @@ Generally, do not contract the words.
Eliminate needless politeness Eliminate needless politeness
----------------------------- -----------------------------
Do not use `please` and `thank you` in technical documentation. Do not use "please" and "thank you" in technical documentation.