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
-    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.
+-------------------------
-
+Always follow naming conventions and trademarks.
-    Clearer:
-    Danger! Stay away from cliff.
-
-Sentence Structure
------------------------------------------------
-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:
+.. good place to link to an Ansible terminology page
-    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.    
+Use clear sentence structure
+----------------------------
+Clear sentence structure means:
 
-Avoid redundant prepositional phrases
+- Start with the important information first.
---------------------------------------------------------------------
+- Avoid padding/adding extra words that make the sentence harder to understand.
-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.
+- Keep it short - Longer sentences are harder to understand.
 
-    Use now instead of at this point in time.
+Some examples of improving sentences:
-    Use suddenly instead of all of a sudden. 
 
-Avoid verbosity
+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.
-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.
 
-Avoid pomposity
+Better:
----------------------------------------
+    Danger! Stay away from the cliff.
-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.
 
-Action verbs, menus, and commands
+Bad:
-----------------------------------------------------------------
+    Furthermore, large volumes of water are also required for the process of extraction.
-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.
 
-The most frequent verbs used in software are:
+Better:
+    Extraction also requires large volumes of water.
 
-- Click
+Avoid verbosity
-- Double-click
+---------------
-- Select
+Write short, succinct sentences. Avoid terms like:
-- Type
-- Press
 
-Use of an action verb in a sentence (**bolded** words):
+- "...as has been said before,"
+- "..each and every,"
+- "...point in time,"
+- "...in order to,"
 
-1. In the dialog box, click **Open**.
+Highlight menu items and commands
-2. **Type** a name in the text box.
+---------------------------------
-3. On the keyboard press **Enter**.
+When documenting menus or commands, it helps to **bold** what is important.
 
-Use of menu actions and commands in a sentence:
+For menu procedures, bold the menu names, button names, etc to help the user find them on the GUI:
 
 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