Restructure and improve Dev Guide

Author: bcantoni

docs/dev-guide.md

@@ -4,7 +4,7 @@ layout: docs
 ---
 
 This topic describes how to contribute to the Tableau Server Client (Python)
-project.
+project:
 
 <!-- prettier-ignore -->
 - TOC
@@ -21,11 +21,9 @@ add your contributions to the **development** branch.
 ### Get the source code and set up your branch
 
 1. Make sure you have
-   [signed the CLA](https://tableau.github.io/contributing.html)
+   [signed the CLA](https://tableau.github.io/contributing.html).
 
-1. Fork the repository.
-
-   We follow the "Fork and Pull" model as described
+1. Fork the repository. We follow the "Fork and Pull" model as described
    [here](https://help.github.com/articles/about-collaborative-development-models/).
 
 1. Clone your fork:
@@ -40,16 +38,14 @@ add your contributions to the **development** branch.
    python setup.py test
    ```
 
-1. Set up the feature, fix, or documentation branch.
-
-   It is recommended to use the format issue#-type-description (e.g.
-   13-fix-connection-bug) like so:
+1. Set up the feature/fix branch (based off the `development` branch). It is
+   recommended to use the format issue#-type-description, for example:
 
    ```shell
-   git checkout -b 13-feature-new-stuff development
+   git checkout -b 13-fix-connection-bug development
    ```
 
-   For documentation changes, see the documentation section below.
+For documentation changes, see the documentation section below.
 
 ### Code and commit
 
@@ -60,42 +56,58 @@ Here's a quick checklist to follow when coding to ensure a good pull request
   goal.
 - Ensure all indentation is done as 4-spaces and your editor is set to unix line
   endings.
-- The code matches PEP8 style guides. If you cloned the repo you can run
-  `pycodestyle tableauserverclient test samples`
-- Keep commit messages clean and descriptive. If the PR is accepted it will get
-  'Squashed' into a single commit before merging, the commit messages will be
-  used to generate the Merge commit message.
+- The code matches PEP8 style guides. Make sure to run
+  `pycodestyle tableauserverclient test samples` to catch and fix any style
+  issues before submitting your pull request.
+- Keep commit messages clean and descriptive.
+
+### Adding features
+
+1. Create an endpoint class for the new feature, following the structure of the
+   other endpoints. Each endpoint usually has `get`, `post`, `update`, and
+   `delete` operations that require making the url, creating the XML request if
+   necessary, sending the request, and creating the target item object based on
+   the server response.
+
+1. Create an item class for the new feature, following the structure of the
+   other item classes. Each item has properties that correspond to what
+   attributes are sent to/received from the server (refer to docs and Postman
+   for attributes). Some items also require constants for user input that are
+   limited to specific strings. After making all the properties, make the
+   parsing method that takes the server response and creates an instances of the
+   target item. If the corresponding endpoint class has an update function, then
+   parsing is broken into multiple parts (refer to another item like workbook or
+   datasource for example).
+
+1. Add testing by getting real xml responses from the server, and asserting that
+   all properties are parsed and set correctly.
+
+1. Add a sample to show users how to use the new feature.
 
 ### Add tests
 
 All of our tests live under the `test/` folder in the repository. We use
-`pytest` and the built-in test runner `python setup.py test`. If a test needs a
-static file, like a .twb/.twbx, it should live under `test/assets/`
+`pytest` and the built-in test runner `python setup.py test`.
 
-### Update the documentation
+Follow the structure of existing tests, especially if new server responses
+are going to be mocked.
 
-When adding a new feature or improving existing functionality we may ask that
-you update the documentation along with your code.
+If a test needs a
+static file, like a .twb/.twbx/.xml, it should live under `test/assets/`
 
-Our documentation is written in markdown and built with Jekyll on GitHub Pages.
-All of the documentation source files can be found in `/docs` folder in the
-**gh-pages** branch. The docs are hosted on the following URL:
-[https://tableau.github.io/server-client-python](https://tableau.github.io/server-client-python)
+Make sure that all tests are passing before submitting your pull request.
 
-If you are just making documentation updates (adding new docs, fixing typos,
-improving wording) the easiest method is to use the built-in `Edit this file`
-feature right in GitHub (click the pencil icon). If you are viewing one of the
-pages on
-[https://tableau.github.io/server-client-python](https://tableau.github.io/server-client-python),
-clicking the **Edit this page** link at the top of the page will take you to the
-same place.
+### Update the documentation
+
+When adding a new feature or improving existing functionality we ask that you
+update the documentation along with your code. See the Updating documentation
+section below for details.
 
-### Commit changes to your fork and open a PR
+### Commit changes to your fork and open a pull request
 
 1. Make a PR as described
    [here](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)
-   against the **development** branch for code changes, or against **gh-pages**
-   for documentation updates.
+   against the **development** branch for code changes.
 
 1. Wait for a review and address any feedback. While we try and stay on top of
    all issues and PRs it might take a few days for someone to respond. Politely
@@ -107,33 +119,38 @@ same place.
    width="5%"} (:rocket:'s) from members of the core team they will merge the
    PR.
 
----
+## Updating documentation
 
-## Add new features
+Our documentation is written in Markdown (specifically
+[kramdown](https://kramdown.gettalong.org/quickref.html)) and built with Jekyll
+on GitHub Pages.
 
-1. Create an endpoint class for the new feature, following the structure of the
-   other endpoints. Each endpoint usually has `get`, `post`, `update`, and
-   `delete` operations that require making the url, creating the XML request if
-   necessary, sending the request, and creating the target item object based on
-   the server response.
+All of the documentation source files can be found in `/docs` folder in the
+**gh-pages** branch. The docs are hosted on the following URL:
+<https://tableau.github.io/server-client-python>.
 
-1. Create an item class for the new feature, following the structure of the
-   other item classes. Each item has properties that correspond to what
-   attributes are sent to/received from the server (refer to docs and Postman
-   for attributes). Some items also require constants for user input that are
-   limited to specific strings. After making all the properties, make the
-   parsing method that takes the server response and creates an instances of the
-   target item. If the corresponding endpoint class has an update function, then
-   parsing is broken into multiple parts (refer to another item like workbook or
-   datasource for example).
+If you are just making documentation updates (adding new docs, fixing typos,
+improving wording) the easiest method is to use the built-in `Edit this file`
+feature (the pencil icon) or the `Edit this page` link.
 
-1. Add testing by getting real xml responses from the server, and asserting that
-   all properties are parsed and set correctly.
+To make more significant changes or additions, please create a pull request
+against the **gh-pages** branch. When submitted along with a code pull request
+(as described above), you can include a link in the PR text so it's clear they
+go together.
 
-1. Add a sample to show users how to use the new feature.
+### Running docs locally
+
+To preview and run the documentation locally, these are the steps:
+
+1. Install [Ruby](https://www.ruby-lang.org/en/downloads/) (v2.5.0 or higher)
+
+1. Install [Bundler](https://bundler.io/)
+
+1. Install [Jekyll](https://jekyllrb.com/docs/installation/)
+
+1. Run the Jekyll site locally with `bundle exec jekyll serve`
 
-<!--
-### Updating Documentation
+1. In your browser, connect to <http://127.0.0.1:4000/server-client-python/>
 
-### Running Tests
--->
+For more details on the steps, see the GitHub Pages topic on
+[testing locally](https://docs.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll).