Merge pull request cockroachdb#1493 from cockroachdb/style-guide-update

Style guide for lists

CONTRIBUTING.md

@@ -4,9 +4,19 @@ The CockroachDB docs are open source just like the database itself. We welcome y
 
 ## Setup
 
-1. Install [Jekyll](https://jekyllrb.com/docs/installation/). CockroachDB uses Jekyll to transform markdown and layout files into a complete, static HTML site. You need to install Jekyll so you can view doc changes locally.
+1. Fork the [CockroachDB docs repository](https://github.com/cockroachdb/docs).
 
-2. Install [HTMLProofer](https://github.com/gjtorikian/html-proofer). This tool lets you check the HTML generated by Jekyll for errors (broken internal and external links, missing images, etc.).
+2. [Create a local clone](https://help.github.com/articles/cloning-a-repository/) of your fork.
+
+3. CockroachDB uses [Jekyll](https://jekyllrb.com/docs/installation/) to transform Markdown and layout files into a complete, static HTML site. We also use [HTMLProofer](https://github.com/gjtorikian/html-proofer) to check the generated HTML for errors (broken internal and external links, missing images, etc.).
+
+    Install Jekyll, HTMLProofer, and some other dependencies so you can view doc changes locally:
+
+    ``` shell
+    $ cd path/to/docs
+    $ gem install bundler
+    $ bundle
+    ```
 
 3. Learn the essentials of our [Docs Structure](#docs-structure).
 
@@ -16,17 +26,21 @@ The CockroachDB docs are open source just like the database itself. We welcome y
 
 Once you're ready to contribute:
 
-1.  Fork the CockroachDB [docs repository](https://github.com/cockroachdb/docs).
+1. Create a new local branch for your work:
+
+   ``` shell
+   $ cd path/to/docs
+   $ git checkout -b "<your branch name>"
 
-2.  [Create a local clone](https://help.github.com/articles/cloning-a-repository/) of your fork.
+3. Make your changes.
 
-3.  Make your changes.
+4. [Build and test the docs locally](#build-and-test-the-docs-locally).
 
-4.  [Build and test the docs locally](#build-and-test-the-docs-locally).
+5. Commit your changes.
 
-5.  [Push to your remote fork](https://help.github.com/articles/pushing-to-a-remote/).
+5. [Push to your local branch to your remote fork](https://help.github.com/articles/pushing-to-a-remote/).
 
-6.  Back in the CockroachDB docs repo, [open a pull request](https://github.com/cockroachdb/docs/pulls) and assign it to `jseldess`.
+6. Back in the CockroachDB docs repo, [open a pull request](https://github.com/cockroachdb/docs/pulls) and assign it to `jseldess`.
 
 We'll review your changes, providing feedback and guidance as necessary. Also, Teamcity, the system we use to automate tests, will run the markdown files through Jekyll and then run [HTMLProofer](https://github.com/gjtorikian/html-proofer) against the resulting HTML output to check for errors. Teamcity will also attempt to sync the HTML to an AWS server, but since you'll be working on your own fork, this part of the process will fail; don't worry about the Teamcity fail status.
 
@@ -182,6 +196,62 @@ SQL code samples are broken into two sections: commands and responses.
 
   Note that not all responses warrant inclusion. For example, if a SQL code sample shows `CREATE TABLE`, `INSERT`, and then `SELECT`, it's unnecessary to show the responses for `CREATE TABLE` (which is just `CREATE TABLE`) and `INSERT` (which is just `INSERT <number of rows>`).
 
+### Lists
+
+For each item of a numbered list, use the step number followed by a period, e.g., `1.`.
+
+For each item of a bulleted list, use the `-` character.
+
+#### Nesting Lists
+
+To nest a list under a list item, start the list on the next line (no empty line), and indent the new list four spaces, for example:
+
+```
+1. This is a step.
+    - This is a bullet.
+    - This is a bullet.
+    - This is a bullet.
+
+2. This is a step.
+```
+
+#### Nesting Paragraphs or Code Blocks
+
+To nest a paragraph or code block under a list item, insert an empty line and then indent the paragraph or code block 4 spaces, for example:
+
+```
+1. This is a step.
+
+    This is a nested paragraph.
+
+    ~~~ shell
+    $ command
+    ~~~
+```
+
+Similarly, to nest a paragraph or code block under a *nested* list item, insert an empty line and then indent the paragraph or code block 8 spaces, for example:
+
+```
+1. This is a step.
+    - This is a bullet.
+
+        ~~~ shell
+        $ command
+        ~~~
+    - This is a bullet.
+
+        ~~~ shell
+        $ command
+        ~~~
+    - This is a bullet.
+
+        ~~~ shell
+        $ command
+        ~~~
+
+2. This is a step.
+```
+
 ### Notes, Warnings, & Tips
 
 Our docs use three classes of highlighted text.
@@ -231,7 +301,7 @@ Once you've installed Jekyll and have a local clone of the docs repository, you
 1.  From the root directory of your clone, run:
 
     ``` shell
-    $ jekyll serve
+    $ jekyll serve --incremental
     ```
 
 2.  Point your browser to `http://127.0.0.1:4000/docs/` and manually check your changes.