[docs] README fixes (#2123)

* [docs] Fix generated files path in README

The path to generated grammar and diagram Markdown files is incorrect.
Rather than `syntax_resources`, it should be
`syntax_resources/commands`.  Fix this in `docs/README.md`.  Also make
minor changes around the area.

* [docs] Remove useless and misleading note

There is a note indicating that the examples following it are based on a
certain working directory and target file.  However, many of the things
following it are not based on that working directory, and the target
file is reintroduced each time.  This makes this note useless, if not
misleading.  Remove it.

* [docs] Fix reference to config.yaml.example

The current `README.md` refers to `config.yaml.sample` when it should be
`config.yaml.example`.  Fix these references.

* [docs] Generalize git add by removing -A flag

`git add -A` should not be promoted in any sort of instructions because
uncareful people may accidentally commit unrelated files.  Generalize
the instructions to `git add ...` because there are plenty of other ways
to add files to the index.

* [doc] Fix the old references to the docs repo

The docs repository is no longer active as it got merged into the main
yugabyte-db repository.  Fix any references to the old docs repo, and
make minor fixes in the surrounding area.

* [docs] Suggest creating a feature branch for PR

The docs README suggests to use the master branch for pull requests.
That is not recommended practice.  Add a suggestion to create a feature
branch.

docs/README.md

@@ -15,16 +15,16 @@ YugaByte DB docs are based on the Hugo framework and use the Material Docs theme
 
 ## Step 1. Initial setup
 
-Follow these steps if this is the first time you are setting up the YugaByte docs repo locally.
+Follow these steps if this is the first time you are setting up for working on the docs locally.
 
 1. Fork this repository on GitHub and create a local clone of your fork. This should look something like below:
 ```
-git clone git@github.com:<YOUR_GITHUB_ID>/docs.git
+git clone git@github.com:<YOUR_GITHUB_ID>/yugabyte-db.git
 ```
 
-Add the master as a remote branch by running the following:
+Add the original repository as an upstream remote:
 ```
-$ git remote add --track master upstream https://github.com/YugaByte/docs.git
+$ git remote add --track master upstream https://github.com/YugaByte/yugabyte-db.git
 ```
 
 2. Install Hugo. For example, on a Mac, you can run the following commands:
@@ -34,17 +34,17 @@ brew install hugo
 brew install npm
 ```
 
-3. Copy the config.yaml.sample to config.yaml.
+3. Copy `config.yaml.example` to `config.yaml`.
 ```
-cp config.yaml.sample config.yaml
+cp config.yaml.example config.yaml
 ```
 
 4. Install node modules as shown below:
 ```
 $ npm ci
 ```
 
-## Step 2. Update your docs repo and start the local webserver
+## Step 2. Update your repo and start the local webserver
 
 The assumption here is that you are working on a local clone of your fork. See the previous step.
 
@@ -83,12 +83,18 @@ You can now share the following link: `http://<YOUR_IP_OR_HOSTNAME>:1313`
 
 ## Step 3. Make changes
 
+It is suggested that you create and checkout a feature branch off `master` for your changes:
+```
+$ git branch <feature branch name> master
+$ git checkout <feature branch name>
+```
+
 Make the changes locally and test them on the browser.
 
 Once you are satisfied with your changes, commit them to your local branch. You can do this by running the following command:
 ```
-# Add all files you have made changes to.
-$ git add -A
+# Add files you have made changes to.
+$ git add ...
 
 # Commit these changes.
 $ git commit
@@ -107,8 +113,7 @@ We will review your changes, add any feedback and once everything looks good mer
 
 To update the documentation with new grammars and syntax diagrams, follow these steps:
 
-_Note: Modifications will typically be added to the `ysql` or `ycql` subdirectories of the `docs/content/latest/api/` directory.
-In the examples below, the subdirectory is `docs/content/latest/api/ysql` and the target file is `commands/cmd_copy.md`._
+_Note: Modifications will typically be added to the `ysql` or `ycql` subdirectories of the `docs/content/latest/api/` directory._
 
 1. Update the appropriate EBNF source grammar file (`<source>_grammar.ebnf`) with your changes, for example, adding support for a new statement or clause.
 
@@ -119,7 +124,7 @@ In the examples below, the subdirectory is `docs/content/latest/api/ysql` and th
 
     _Example: for the YSQL `COPY` command the source file is `./content/latest/api/ysql/commands/cmd_copy.md`._
 
-3. Inside of the syntax_resources directory, create the following two empty files:
+3. Inside of the `syntax_resources/commands` directory, create the following two **empty** files:
     - `<name>.grammar.md`
     - `<name>.diagram.md`
 
@@ -145,12 +150,14 @@ In the examples below, the subdirectory is `docs/content/latest/api/ysql` and th
     java -jar rrdiagram.jar <input-file.ebnf> <output-folder>
     ```
 
+    `<output-folder>` should end in `syntax_resources`, not `commands`, to get helpful `WARNING`s.
+
     _Example: To generate the syntax diagrams for the YSQL API, run the following command:_
-    ```
+    ```bash
     java -jar rrdiagram.jar content/latest/api/ysql/syntax_resources/ysql_grammar.ebnf content/latest/api/ysql/syntax_resources/
     ```
 
-    All of the Markdown (`.md`) files in the `./ysql/syntax_resources` directory will be generated as needed.
+    All of the Markdown (`.md`) files in the `./ysql/syntax_resources/commands` directory will be generated as needed.
 
     _Note: To see help, run `java -jar rrdiagram.jar` (without arguments)._