Styleguide basic (#49747)

* cleaned up basics page

* made codeblock visible

* added anchor

docs/docsite/rst/dev_guide/style_guide/basic_rules.rst

@@ -1,83 +1,69 @@
-Basic Rules
+.. _styleguide_basic:
-``````````````````
-Use Standard American English
----------------------------------------
-Ansible has customers/users all around the globe, but the headquarters is in Durham, NC, in the US. Use Standard American English rather than other variations of the English language.
 
-Write for a Global Audience
+Basic rules
-------------------------------------
+===========
-The idea behind global writing is that everything you say should be understandable by those of many different backgrounds and cultures. References, therefore, should be as universal as possible. Avoid idioms and regionalism and maintain a neutral tone that cannot be misinterpreted. Avoid attempts at humor.
+.. contents::
+  :local:
 
-Follow Naming Conventions
+Use standard American English
----------------------------------------
+-----------------------------
-Always follow naming conventions and trademarks. If you aren't sure how a product should be properly referred to, ask the Engineering Product Manager of that product line (ansible-core or Tower) for information.
+Ansible uses Standard American English. Watch for common words that are spelled differently in American English (color vs colour, organize vs organise, etc.).
 
-Important Information First
+Write for a global audience
-----------------------------------------------
+---------------------------
-Important information stated at the beginning of a sentence makes it easier to understand.
+Everything you say should be understandable by people of different backgrounds and cultures. Avoid idioms and regionalism and maintain a neutral tone that cannot be misinterpreted. Avoid attempts at humor.
 
-    Unclear:
+Follow naming conventions
+-------------------------
+Always follow naming conventions and trademarks.
+
+.. good place to link to an Ansible terminology page
+
+Use clear sentence structure
+----------------------------
+Clear sentence structure means:
+
+- Start with the important information first.
+- Avoid padding/adding extra words that make the sentence harder to understand.
+- Keep it short - Longer sentences are harder to understand.
+
+Some examples of improving sentences:
+
+Bad:
     The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety.
 
-    Clearer:
+Better:
-    Danger! Stay away from cliff.
+    Danger! Stay away from the cliff.
 
-Sentence Structure
+Bad:
------------------------------------------------
-Good sentence structure helps convey information. Try to keep the most important information towards the beginning of the sentence.
-
-    Bad:
     Furthermore, large volumes of water are also required for the process of extraction.
 
-    Better:
+Better:
-    Extraction also requires large volumes of water. 
+    Extraction also requires large volumes of water.
-    
-Avoid padding
--------------------------------
-
-When reading a piece of technical writing, the audience does not benefit from elaborate prose. They just need information on how to perform a task. Avoid using padding, or filler. Don't use phrases such as, kind of, sort of, and essentially.    
-
-Avoid redundant prepositional phrases
---------------------------------------------------------------------
-Prepositional phrases, the combination of a preposition with a noun phrase, are among the worst offenders in making text long and tiresome to read. Often, it is possible to replace an entire phrase with a single word.
-
-    Use now instead of at this point in time.
-    Use suddenly instead of all of a sudden. 
 
 Avoid verbosity
-------------------------------------
+---------------
-Write short, succinct sentences. Never say, "...as has been said before," "..each and every," "...point in time," etc. Avoid "...in order to," especially at the beginning of sentences. Every word must contribute meaning to the sentence. Technical writing is information delivery.
+Write short, succinct sentences. Avoid terms like:
 
-Avoid pomposity
+- "...as has been said before,"
----------------------------------------
+- "..each and every,"
-While it is good to have a wide vocabulary, technical writing is not the place for showing off linguistic abilities. Technical writing is about producing clear, plain instructions for a specific audience.
+- "...point in time,"
+- "...in order to,"
 
-Action verbs, menus, and commands
+Highlight menu items and commands
-----------------------------------------------------------------
+---------------------------------
-We interact with computers in a variety of ways. You can select anything on an application user interface by selecting it using a keyboard or mouse. It is important to use action verbs and software terminology correctly.
+When documenting menus or commands, it helps to **bold** what is important.
 
-The most frequent verbs used in software are:
+For menu procedures, bold the menu names, button names, etc to help the user find them on the GUI:
-
-- Click
-- Double-click
-- Select
-- Type
-- Press
-
-Use of an action verb in a sentence (**bolded** words):
-
-1. In the dialog box, click **Open**.
-2. **Type** a name in the text box.
-3. On the keyboard press **Enter**.
-
-Use of menu actions and commands in a sentence:
 
 1. On the **File** menu, click **Open**.
-2. **Type** a name in the **User Name** field.
+2. Type a name in the **User Name** field.
 3. In the **Open** dialog box, click **Save**.
-4. On the computer keyboard, press **Enter**.
+4. On the toolbar, click the **Open File** icon.
-5. On the toolbar, click the **Open File** icon.
 
-Make users aware of where they are in the application. If there is more than one method to perform an action, use the most common method. Define "what, where, and how" in each step of the task or procedure. Describe menu items for the current task left to right, top-down.
+For code or command snippets, use the RST `code-block directive <http://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_::
 
+   .. code-block:: bash
 
+     ssh my_vyos_user@vyos.example.net
+     show config