openstack/openstack-manuals
Code Issues Proposed changes

Added a section about the writing style

Browse Source 
Converted to the .rst format, modified, and extended this section:
https://wiki.openstack.org/wiki/Documentation/Conventions

Change-Id: I836ebed9c08bdd22395d9ff436e480f025f3d268
Implements: blueprint docs-contributor-guide
This commit is contained in:
Svetlana Karslioglu 2015-09-03 19:12:59 -07:00
parent dd947dc372
commit 866af89727
7 changed files with 504 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/contributor-guide/source/index.rst
View File

@ -20,9 +20,9 @@ Contents
docs-structure.rst
content-specs.rst
docs_builds.rst
writing-style.rst
Search in this guide
~~~~~~~~~~~~~~~~~~~~
* :ref:`search`

19
doc/contributor-guide/source/writing-style.rst Normal file
View File

@ -0,0 +1,19 @@
.. _stg_writing_style:
=============
Writing style
=============
This section describes general writing style guidelines that
documentation contributors should follow to ensure consistency
throughout all technical publications.
.. toctree::
:maxdepth: 2
writing-style/general-writing-guidelines.rst
writing-style/word-choice.rst
writing-style/openstack-components.rst
writing-style/release-names.rst
writing-style/code-conventions.rst

29
doc/contributor-guide/source/writing-style/code-conventions.rst Normal file
View File

@ -0,0 +1,29 @@
.. _code_conventions:
Code conventions
~~~~~~~~~~~~~~~~
Follow these guidelines:
* **Do not use ``-y`` for package install**
When you describe package installation, do not use the ``-y`` option.
Instead, use ``apt-get install package``, ``yum install package``, or
``zypper install package``.
* **Use ``--option ARGUMENT``**
The OpenStack CLI commands such as ``keystone`` support both
``--option ARGUMENT`` and ``--option=ARGUMENT``. In technical publications,
use ``--option ARGUMENT``.
.. note::
Nova exposes both its own API and an EC2-compatible API. Therefore, you can
complete many tasks by using either the nova CLI or ``euca2ools``.
When documenting ``euca2ools``, limit the content to the following topics:
* Tasks required to get credentials to work with ``euca2ools``
* Explain the difference in operation between the Amazon EC2 and
OpenStack endpoints when you access them through EC2.

346
doc/contributor-guide/source/writing-style/general-writing-guidelines.rst Normal file
View File

@ -0,0 +1,346 @@
.. _stg_gen_write_guidelines:
General writing guidelines
~~~~~~~~~~~~~~~~~~~~~~~~~~
Follow these guidelines to ensure readability and consistency of the
OpenStack documentation.
Use standard English
--------------------
Use standard United States (U.S.) English throughout all technical
publications.
When in doubt about the spelling of a word, consult the
`Merriam-Webster's Collegiate Dictionary` and the `IBM Style Guide
<http://www.redbooks.ibm.com/Redbooks.nsf/ibmpressisbn/9780132101301?Open>`_.
Write in active voice
---------------------
In general, write in active voice rather than passive voice.
Active voice identifies the agent of action as the subject of the verb —
usually the user.
Passive voice identifies the recipient (not the source) of the action
as the subject of the verb.
Active-voice sentences clarify the performer of an action and are easier
to understand than passive-voice sentences. Passive voice is usually less
engaging and more complicated than active voice. When you use passive voice,
the actions and responses of the software can be difficult to distinguish
from those of the user. In addition, passive voice usually requires more
words than active voice.
**Example of usage**
+---------------------------------+------------------------------------+
| **Do not use** | **Use** |
+=================================+====================================+
| After the software has been | After you install the software, |
| installed, the computer can be | start the computer. |
| started. | |
+---------------------------------+------------------------------------+
| The Configuration is saved when | Click **OK** to save the |
| you click **OK**. | configuration. |
+---------------------------------+------------------------------------+
| A server is created by you. | Create a server. |
+---------------------------------+------------------------------------+
However, passive voice is acceptable in the following situations:
* Using active voice sounds like you are blaming the user. For example, you
can use passive voice in an error message or troubleshooting content when
the active subject is the user.
**Example of usage**
+---------------------------------+------------------------------------+
| **Do not use** | **Use** |
+=================================+====================================+
| If the build fails, you probably| If the build fails, the flavor |
| omitted the flavor. | might have been omitted. |
+---------------------------------+------------------------------------+
* The agent of action is unknown, or you want to de-emphasize the agent of
action and emphasize the object on which the action is performed.
**Example of usage**
+---------------------------------+------------------------------------+
| **Do not use** | **Use** |
+=================================+====================================+
| The product, OS, or database | The messages are returned [by the |
| returns the messages. | database]. |
+---------------------------------+------------------------------------+
* Recasting the sentence in active voice is wordy or awkward.
**Example of usage**
+---------------------------------+------------------------------------+
| **Do not use** | **Use** |
+=================================+====================================+
| In 2009 engineers developed a | A software that simplifies the |
| software that simplifies the | installation was developed in 2009.|
| installation. | |
+---------------------------------+------------------------------------+
Use the present simple tense
----------------------------
Users read documentation to perform tasks or gather information. For users,
these activities take place in their present, so the present tense is
appropriate in most cases. Additionally, the present tense is easier to read
than the past or future tense.
Use the future tense only when you need to emphasize that something will occur
later (from the users' perspective).
**Example of usage**
+------------------------------------+---------------------------------------+
| **Do not use** | **Use** |
+====================================+=======================================+
| The product will prompt you to | The product prompts you to verify |
| verify the deletion. After you log | the deletion. |
| in, your account will then begin | After you log in, your account you |
| the verification process. | account begins the verification |
| | process. |
+------------------------------------+---------------------------------------+
Write in second person
----------------------
Users are more engaged with documentation when you use second person (that is,
you address the user as `you`).
Writing in second person has the following advantages:
* Second person promotes a friendly tone by addressing users directly.
* Using second person with the imperative mood (in which the subject you
is understood) and active voice helps to eliminate wordiness and confusion
about who or what initiates an action, especially in procedural steps.
* Using second person also avoids the use of gender-specific, third-person
pronouns such as he, she, his, and hers. If you must use third person, use
the pronouns they and their, but ensure that the pronoun matches the
referenced noun in number.
Use first person plural pronouns (we, our) judiciously. These pronouns
emphasize the writer or OpenStack rather than the user, so before you use
them, consider whether second person or imperative mood is more
"user-friendly." However, use `we recommend` rather than `it is recommended`
or `OpenStack recommends`.
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
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
object on which the action is performed, use passive voice.
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
actions or opinions.
Do not switch person (point of view) in the same document.
**Example of usage**
+--------------------------------+-----------------------------------+
| **Do not use** | **Use** |
+================================+===================================+
| Creating a server involves | To create a server, specify a |
| specifying a name, flavor, | name, a flavor, and image. |
| and image. | |
| | |
| To create a server, the user | To create a server, you specify a |
| specifies a name, flavor, and | name, flavor, and image. |
| image. | |
+--------------------------------+-----------------------------------+
Use appropriate mood
--------------------
For procedures, use imperative mood.
**Example:**
Start the installation by pressing **Enter**.
For explanations, use indicative mood.
**Example:**
The script automatically provisions virtual machines with all required
settings.
Do not use subjunctive mood.
**Example of usage**
+-------------------------------------+------------------------------------+
| **Do not use** | **Use** |
+=====================================+====================================+
| If you were to deploy OpenStack... | If you want to deploy OpenStack... |
| (Implied: but you are not) | |
+-------------------------------------+------------------------------------+
Keep sentences short
--------------------
Short and simple sentences are easier to read and understand.
Follow the principles of minimalism
-----------------------------------
If you can describe an idea in one word, do not use two words.
Eliminate all redundant modifiers, such as adjectives and adverbs.
Write objectively
-----------------
Do not use humor, jargon, exclamation marks, idioms, metaphors, and
other colloquialisms.
Describe the most common use case first
---------------------------------------
Put the most common case in the main clause and at the beginning of a
paragraph or section. You can introduce additional
use cases by starting a sentence with `however` or `if`.
Do not humanize inanimate objects
---------------------------------
Do not give human characteristics to non-human subjects or objects.
**Example of usage**
+-----------------------+---------------------+
| **Do not use** | **Use** |
+=======================+=====================+
| This guide assumes | This guide describes|
+-----------------------+---------------------+
Write positively
----------------
Write in positive tone. Positive sentences improve readability.
Try to avoid the following words as much as possible:
**Example of usage**
+------------------------+----------------------------------+
| **Do not use** | **Use** |
+========================+==================================+
| damage | affect |
+------------------------+----------------------------------+
| catastrophic | serious |
+------------------------+----------------------------------+
| bad | Use `serious` or add explanation |
+------------------------+----------------------------------+
| fail | unable to |
+------------------------+----------------------------------+
| kill | cancel |
+------------------------+----------------------------------+
| fatal | serious |
+------------------------+----------------------------------+
| destroy | remove |
+------------------------+----------------------------------+
| wrong | incorrect, inconsistent |
+------------------------+----------------------------------+
Avoid prepositions at the end of sentences
------------------------------------------
As much as possible, avoid trailing prepositions in sentences by
avoiding phrasal verbs.
**Example of usage**
+------------------------+--------------------------+
| **Ambiguous** | **Better** |
+========================+==========================+
| The image registration | The image registration |
| window will open up. | window opens. |
+------------------------+--------------------------+
To fix the verb-preposition constructions, replace them with active
verbs.
**Example of usage**
+-------------------------+------------------------+
| **Ambiguous** | **Better** |
+=========================+========================+
| written up | composed |
+-------------------------+------------------------+
| pop up | appear |
+-------------------------+------------------------+
Do no overuse this, that, these, and it
---------------------------------------
Use these pronouns sparingly. Overuse contributes to readers'
confusion. To fix the ambiguity, rephrase the sentence.
**Example of usage**
+-------------------------+-------------------------------+
| **Ambiguous** | **Better** |
+=========================+===============================+
| The monitoring system | The monitoring system performs|
| should perform regular | regular checks to ensure the |
| checks to verify that | Ceph cluster is functioning |
| the Ceph cluster is | correctly. Use the |
| healthy. This can be | ``ceph health`` command to run|
| achieved using the | a health check. |
| Ceph health command. | |
+-------------------------+-------------------------------+
You can also fix the ambiguity by placing a noun modifier immediately
after the pronoun.
Do not split infinitives
------------------------
Do not place modifiers between `to` and the verb. Typically, placing
an adverb or an adjective between `to` and a verb adds ambiguity to
a sentence.
However, in some cases it is acceptable.
**Example:**
To significantly improve...
Avoid personification
---------------------
Do not express your fears or feelings in technical writing. Avoid
the adverbs such as `probably`, `hopefully`, `basically`, and so on.
Do not use contractions
-----------------------
Generally, do not contract the words.
**Example of usage**
+------------------------+--------------------+
| **Do not use** | **Use** |
+========================+====================+
| can't | cannot |
+------------------------+--------------------+
| don't | do not |
+------------------------+--------------------+
Eliminate needless politeness
-----------------------------
Do not use `please` and `thank you` in technical documentation.

20
doc/contributor-guide/source/writing-style/openstack-components.rst Normal file
View File

@ -0,0 +1,20 @@
.. _openstack_term:
OpenStack service and project names
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use uppercase when you refer to a service name. For example, use
*Compute service*, *Image service*, or *Identity service* instead
of *nova*, *glance*, or *keystone*.
Use lowercase when you refer to:
* project names
* project team names
* command-line interface (CLI)
The official source for services and project names is in the OpenStack
governance repository in the
`projects.yaml <http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml>`_
file.

12
doc/contributor-guide/source/writing-style/release-names.rst Normal file
View File

@ -0,0 +1,12 @@
.. _release_names:
Release names
~~~~~~~~~~~~~
Use the names of the OpenStack releases as described on
`this wiki page <https://wiki.openstack.org/wiki/Releases>`_.
**Example:**
Icehouse - a single word with only initial capital.

77
doc/contributor-guide/source/writing-style/word-choice.rst Normal file
View File

@ -0,0 +1,77 @@
.. _stg_word_choice:
Word choice
~~~~~~~~~~~
This section offers conventions around general English usage and the terms that
are not covered in the
`glossary <http://docs.openstack.org/glossary/content/glossary.html>`_.
Additionally, use the `IBM
Terminology <http://www-01.ibm.com/software/globalization/terminology/>`_ as
a reference.
The following table lists the preferred word or phrase choice.
**Preferred word choice**
+----------------+----------------------+
| **Word** | **Do not use** |
+================+======================+
| and so on | etc. |
+----------------+----------------------+
| back end (noun)| backend, back-end |
| | In general, avoid. |
| | Use a more specific |
| | term, such as |
| | server, operating |
| | system, or network. |
+----------------+----------------------+
| back-end (adj) | backend, back end |
+----------------+----------------------+
| cancel | abort |
| | |
+----------------+----------------------+
| complete | done, finish |
+----------------+----------------------+
| command line | command-line |
| (noun) | |
+----------------+----------------------+
| command-line | command line |
| (adj) | |
+----------------+----------------------+
| datastore | data store |
+----------------+----------------------+
| delete | destroy |
+----------------+----------------------+
| to do something| in order to do |
| | something |
+----------------+----------------------+
| Ethernet | ethernet |
+----------------+----------------------+
| example | i.e, e.g. |
+----------------+----------------------+
| hostname | host name, Hostname |
+----------------+----------------------+
| login (noun) | logon, log-in |
+----------------+----------------------+
| log in (verb) | login |
+----------------+----------------------+
| open | launch |
+----------------+----------------------+
| OpenStack | openstack, Openstack |
+----------------+----------------------+
| select | check |
+----------------+----------------------+
| set up (verb) | setup |
+----------------+----------------------+
| an SQL | a SQL |
+----------------+----------------------+
| start | execute |
+----------------+----------------------+
| such as | like |
+----------------+----------------------+
| verify | be sure |
+----------------+----------------------+
| X-as-a-Service | X as a Service |
+----------------+----------------------+