Update Docs: Contributing “writing-style-guide” (#6627)

Co-authored-by: Martin Jagodic <jagodicmartin1@gmail.com>

website/content/docs/writing-style-guide.md

@@ -1,19 +1,20 @@
 ---
-title: Writing Style Guide
-weight: 30
 group: Contributing
+weight: 30
+title: Writing Style Guide
 ---
-
 # Decap CMS Style Guide
-_Adapted from the [Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide)_
+
+*Adapted from the [Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide)*
+
 
 ## Documentation Formatting Standards
 
 ### Use angle brackets for placeholders
 
 Use angle brackets for placeholders. Tell the reader what a placeholder represents.
 
-1. Display information about a cli command:
+1. Display information about a CLI command:
 
 ```bash
 npm install <package-name>
@@ -26,53 +27,62 @@ where `<package-name>` is the name of a package.
 Do: Click **Save**.
 
 Don't: Click "Save".
-_____
+
+- - -
 
 Do: Select **Log Out**.
 
 Don't: Select 'Log Out'.
-_____
+
+- - -
 
 ### Use italics to define or introduce new terms
 
-Do: A _collection_ is a set of entries …
+Do: A *collection* is a set of entries …
 
 Don't: A "collection" is a set of entries …
-_____
 
-Do: These components form the _control pane_.
+- - -
+
+Do: These components form the *control pane*.
 
 Don't: These components form the **control pane**.
-_____
+
+- - -
 
 ### Use code style for filenames, directories, and paths
 
 Do: Open the `config.yaml` file.
 
 Don't: Open the config.yaml file.
-_____
+
+- - -
 
 Do: Go to the `/docs/guides` directory.
 
 Don't: Go to the /docs/guides directory.
-_____
+
+- - -
 
 Do: Open the `/admin/index.html` file.
 
 Don't: Open the /admin/index.html file.
-_____
+
+- - -
 
 ### Use the international standard for punctuation inside quotes
 
 Do: Branch names begin with "cms".
 
 Don't: Branch names begin with "stage."
-_____
+
+- - -
 
 Do: The copy is called a "fork".
 
 Don't: The copy is called a "fork."
-_____
+
+- - -
 
 ## Inline code formatting
 
@@ -83,29 +93,34 @@ For inline code in an HTML document, use the `<code>` tag. In a Markdown documen
 Do: The `yarn start` command starts the development server.
 
 Don't: The "yarn start" command starts the development server.
-_____
+
+- - -
 
 Do: For a production build, use `yarn build`.
 
 Don't: For a production build, use "yarn build".
-_____
 
-Do: Enclose code samples with triple backticks. `(```)`
+- - -
+
+Do: Enclose code samples with triple backticks. ````(```)````
 
-Don't:Enclose code samples with any other syntax.
-_____
+Don't: Enclose code samples with any other syntax.
+
+- - -
 
 ### Use code style for object field names
 
 Do: Set the value of the `media_folder` field in the configuration file.
 
 Don't: Set the value of the "media_folder" field in the configuration file.
-_____
+
+- - -
 
 Do: The value of the `name` field is a string.
 
 Don't: The value of the "name" field is a string.
-_____
+
+- - -
 
 ### Use normal style for string and integer field values
 
@@ -114,17 +129,20 @@ For field values of type string or integer, use normal style without quotation m
 Do: Set the value of `publish_mode` to editorial_workflow.
 
 Don't: Set the value of `imagePullPolicy` to "Always".
-_____
+
+- - -
 
 Do: Set the value of `image` to nginx:1.8.
 
 Don't: Set the value of `image` to `nginx:1.8`.
-_____
+
+- - -
 
 Do: Set the value of the `replicas` field to 2.
 
 Don't: Set the value of the `replicas` field to 2.
-_____
+
+- - -
 
 ## Code snippet formatting
 
@@ -151,12 +169,14 @@ Exception: Use future or past tense if it is required to convey the correct mean
 Do: You can explore the API using a browser.
 
 Don't: The API can be explored using a browser.
-_____
+
+- - -
 
 Do: The YAML file specifies the collection name.
 
 Don't: The collection name is specified in the YAML file.
-_____
+
+- - -
 
 Exception: Use passive voice if active voice leads to an awkward construction.
 
@@ -167,24 +187,28 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying
 Do: To create an entry, …
 
 Don't: In order to create an entry, …
-_____
+
+- - -
 
 Do: See the configuration file.
 
 Don't: Please see the configuration file.
-_____
+
+- - -
 
 Do: View the fields.
 
 Don't: With this next command, we'll view the fields.
-_____
+
+- - -
 
 ### Address the reader as “you”
 
 Do: You can create a Deployment by …
 
 Don't: We'll create a Deployment by …
-_____
+
+- - -
 
 Do: In the preceding output, you can see…
 
@@ -197,12 +221,14 @@ Prefer English terms over Latin abbreviations.
 Do: For example, …
 
 Don't: e.g., …
-_____
+
+- - -
 
 Do: That is, …
 
 Don't: i.e., …
-_____
+
+- - -
 
 Exception: Use “etc.” for et cetera.
 
@@ -215,17 +241,20 @@ Using “we” in a sentence can be confusing, because the reader might not know
 Do: Version 1.4 includes …
 
 Don't: In version 1.4, we have added …
-_____
+
+- - -
 
 Do: Decap CMS provides a new feature for …
 
 Don't: We provide a new feature …
-_____
+
+- - -
 
 Do: This page teaches you how to use Widgets.
 
 Don't: In this page, we are going to learn about Widgets.
-_____
+
+- - -
 
 ### Avoid jargon and idioms
 
@@ -234,12 +263,14 @@ Some readers speak English as a second language. Avoid jargon and idioms to help
 Do: Internally
 
 Don't: Under the hood, …
-_____
+
+- - -
 
 Do: Create a new cluster.
 
 Don't: Turn up a new cluster.
-_____
+
+- - -
 
 ### Avoid statements about the future
 
@@ -252,9 +283,11 @@ Avoid words like “currently” and “new.” A feature that is new today will
 Do: In version 1.4, …
 
 Don't: In the current version, …
-_____
+
+- - -
 
 Do: The Federation feature provides …
 
 Don't: The new Federation feature provides …
-_____
+
+- - -