[incubator-datasketches-website] branch master updated: Update minor changes to README.md

[le...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

leerho pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-datasketches-website.git


The following commit(s) were added to refs/heads/master by this push:
     new 5795583  Update minor changes to README.md
5795583 is described below

commit 57955839cc62637ab74db0cda31dcc678f68f1c8
Author: Lee Rhodes <le...@users.noreply.github.com>
AuthorDate: Fri Jun 5 17:18:58 2020 -0700

    Update minor changes to README.md
---
 README.md | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index bda1444..13951ae 100644
--- a/README.md
+++ b/README.md
@@ -23,24 +23,31 @@ This is the DataSketches website source.  Please visit the main [DataSketches we
 
 If you are interested in making contributions to this site please see our [Community](https://datasketches.apache.org/docs/Community/) page for how to contact us.
 
-### How the documentation website works
+### How the website works
+- The website is published directly from a specially named *asf-site* branch. The content of this branch is generated automatically by *Jekyll* from the *master* branch whenever changes are detected in the *master* branch.  One should never modify the content of the *asf-site* directly.
 
-The page content for the website is rendered directly from markdown documents.  These markdown documents are all referenced according to a table of contents JSON document.  The HTML for the website navigation is generated dynamically from the JSON structure.
+- The *master* branch consists primarily of GitHub compatible *MarkDown* documents, which hold all the written content. 
+
+- There are two navigation mechanisms on the site to help the user find documents: the *nav_bar* at the top of each page and the table-of-contents *toc* drop-down menus on the left of each page.  Individual pages can link to each other using standard MarkDown links.
 
 ### How to contribute content to the website
 
 In order to contribute changes to the website content, you will need to fork this repository to your own GitHub profile.
 
-If you would like to change an existing page, changes can be made directly to the relevant markdown document, and a pull request submitted.  However, should you intend to add a new page to the website, you will need to:
+If you only need to change an existing page, edit the relevant MarkDown page locally and submit a pull-request to *master*.  
+
+However, if you need to add a new page to the website, you may need to modify the *toc* to enable users to find it:
+
+- Create the new MarkDown document with the appropriate layout definition, and copyright notice.  This can be copied from any of the existing pages. The types of available layouts can be found in the */_layouts/* directory. Almost all site documents use the *doc_page* layout.  Place the new page in an appropriate subdirectory in *master*.
 
-- Create a new markdown document with the appropriate layout definition, and copyright notice.  This can be copied from any of the existing pages.
+- The *toc* is generated statically by the developer/author, when it needs to be updated, by running a small Java program called `TocGenerator.java` located in */src/main/java/org/datasketches/docgen/*.  The TocGenerator takes input from the */src/main/resources/docgen/toc.json* file and save the output html in */_includes/toc.html* in *master*.  Please do not edit the *toc.html* file directly. 
 
-- Ensure that there is a new entry in the table of contents JSON document. This file is named `toc.json`, and may be located in the `resources/docgen` subdirectory.
+- The *toc.json* file is pretty easy to figure out. It is a tree structure of two types of elements, *Dropdown* and *Doc*. Each element has 4 or 5 *key:valu*e pairs. Make sure you structure the JSON correctly with matching braces and brackets, and with commas between tree elements.
 
 - Run the table of contents generator.  The `runTocGenerator` method is a static member of `TocGenerator.java`. You can run this from your preferred IDE or from the command line.  You should see the genenerated HTML as output to the console.
 
-- Once you have run the generator, ensure that your new entry is included in the `toc.html` file under the `_includes`
-  subdirectory.
+- Once you have run the generator, ensure that your new entry is included in the `toc.html` file under the `_includes` subdirectory.
+- If you have Jekyll installed on your computer you can visually check the *toc* for proper operation before submitting your PR.
 
 - Lastly, submit your pull request for review!
 


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org