ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

Styleguide basic (#49747)

Browse source 
* cleaned up basics page

* made codeblock visible

* added anchor
This commit is contained in:
Sandra McCann 2018-12-10 15:30:34 -05:00 committed by Alicia Cozine
parent b924476d63
commit 32c2b3b3be
1 changed files with 49 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
docs/docsite/rst/dev_guide/style_guide/basic_rules.rst
View file

@ -1,83 +1,69 @@
Basic Rules
``````````````````
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.
.. _styleguide_basic:
Write for a Global Audience
------------------------------------
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.
Basic rules
===========
.. contents::
:local:
Follow Naming Conventions
---------------------------------------
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.
Use standard American English
-----------------------------
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
----------------------------------------------
Important information stated at the beginning of a sentence makes it easier to understand.
Write for a global audience
---------------------------
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:
Danger! Stay away from cliff.
Better:
Danger! Stay away from the cliff.
Sentence Structure
-----------------------------------------------
Good sentence structure helps convey information. Try to keep the most important information towards the beginning of the sentence.
Bad:
Bad:
Furthermore, large volumes of water are also required for the process of extraction.
Better:
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.
Better:
Extraction also requires large volumes of water.
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
---------------------------------------
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.
- "...as has been said before,"
- "..each and every,"
- "...point in time,"
- "...in order to,"
Action verbs, menus, 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.
Highlight menu items and commands
---------------------------------
When documenting menus or commands, it helps to **bold** what is important.
The most frequent verbs used in software are:
- 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:
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**.
5. On the toolbar, click the **Open File** icon.
4. 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