From 866af897271c17d18d2577972cf53b3e2e9a7780 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Thu, 3 Sep 2015 19:12:59 -0700 Subject: [PATCH] Added a section about the writing style 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 --- doc/contributor-guide/source/index.rst | 2 +- .../source/writing-style.rst | 19 + .../source/writing-style/code-conventions.rst | 29 ++ .../general-writing-guidelines.rst | 346 ++++++++++++++++++ .../writing-style/openstack-components.rst | 20 + .../source/writing-style/release-names.rst | 12 + .../source/writing-style/word-choice.rst | 77 ++++ 7 files changed, 504 insertions(+), 1 deletion(-) create mode 100644 doc/contributor-guide/source/writing-style.rst create mode 100644 doc/contributor-guide/source/writing-style/code-conventions.rst create mode 100644 doc/contributor-guide/source/writing-style/general-writing-guidelines.rst create mode 100644 doc/contributor-guide/source/writing-style/openstack-components.rst create mode 100644 doc/contributor-guide/source/writing-style/release-names.rst create mode 100644 doc/contributor-guide/source/writing-style/word-choice.rst diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index 4ffb664c0d..a406b6cf58 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -20,9 +20,9 @@ Contents docs-structure.rst content-specs.rst docs_builds.rst + writing-style.rst Search in this guide ~~~~~~~~~~~~~~~~~~~~ * :ref:`search` - diff --git a/doc/contributor-guide/source/writing-style.rst b/doc/contributor-guide/source/writing-style.rst new file mode 100644 index 0000000000..9ae3997e41 --- /dev/null +++ b/doc/contributor-guide/source/writing-style.rst @@ -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 diff --git a/doc/contributor-guide/source/writing-style/code-conventions.rst b/doc/contributor-guide/source/writing-style/code-conventions.rst new file mode 100644 index 0000000000..290ad6c8c4 --- /dev/null +++ b/doc/contributor-guide/source/writing-style/code-conventions.rst @@ -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. diff --git a/doc/contributor-guide/source/writing-style/general-writing-guidelines.rst b/doc/contributor-guide/source/writing-style/general-writing-guidelines.rst new file mode 100644 index 0000000000..8168add415 --- /dev/null +++ b/doc/contributor-guide/source/writing-style/general-writing-guidelines.rst @@ -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 +`_. + +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. diff --git a/doc/contributor-guide/source/writing-style/openstack-components.rst b/doc/contributor-guide/source/writing-style/openstack-components.rst new file mode 100644 index 0000000000..dfd7b52851 --- /dev/null +++ b/doc/contributor-guide/source/writing-style/openstack-components.rst @@ -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 `_ +file. + diff --git a/doc/contributor-guide/source/writing-style/release-names.rst b/doc/contributor-guide/source/writing-style/release-names.rst new file mode 100644 index 0000000000..ac5fab460b --- /dev/null +++ b/doc/contributor-guide/source/writing-style/release-names.rst @@ -0,0 +1,12 @@ +.. _release_names: + +Release names +~~~~~~~~~~~~~ + +Use the names of the OpenStack releases as described on +`this wiki page `_. + +**Example:** + +Icehouse - a single word with only initial capital. + diff --git a/doc/contributor-guide/source/writing-style/word-choice.rst b/doc/contributor-guide/source/writing-style/word-choice.rst new file mode 100644 index 0000000000..bb5a3421a5 --- /dev/null +++ b/doc/contributor-guide/source/writing-style/word-choice.rst @@ -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 `_. +Additionally, use the `IBM +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 | ++----------------+----------------------+