link to DOCS_README

docs/DOCS_README.md

@@ -1,16 +1,69 @@
-# Documentation Maintenance Overview
+# Docs Build Workflow
 
-The documentation found in this directory is hosted at:
+The documentation for the Cosmos SDK is hosted at:
 
-- https://cosmos.network/docs/
+- https://cosmos.network/docs/ and
+- https://cosmos-staging.interblock.io/docs/
 
-and built using [VuePress](https://vuepress.vuejs.org/) from the Cosmos website repo:
+built from the files in this (`/docs`) directory for
+[master](https://github.com/cosmos/cosmos-sdk/tree/master/docs)
+and [develop](https://github.com/cosmos/cosmos-sdk/tree/develop/docs),
+respectively.
 
-- https://github.com/cosmos/cosmos.network
+## How It Works
 
-Under the hood, Jenkins listens for changes (on develop or master) in ./docs then rebuilds
-either the staging or production site depending on which branch the changes were made.
+There is a Jenkins job listening for changes in the `/docs` directory, on both
+the  `master` and `develop` branches. Any updates to files in this directory
+on those branches will automatically trigger a website deployment. Under the hood,
+a private website repository has make targets consumed by a standard Jenkins task.
 
-To update the Table of Contents (layout of the documentation sidebar), edit the
-`config.js` in this directory, while the `README.md` is the landing page for the
-website documentation.
+## README
+
+The [README.md](./README.md) is also the landing page for the documentation
+on the website.
+
+## Config.js
+
+The [config.js](./config.js) generates the sidebar and Table of Contents
+on the website docs. Note the use of relative links and the omission of
+file extensions. Additional features are available to improve the look
+of the sidebar.
+
+## Links
+
+**NOTE:** Strongly consider the existing links - both within this directory
+and to the website docs - when moving or deleting files.
+
+Relative links should be used nearly everywhere, having discovered and weighed the following:
+
+### Relative
+
+Where is the other file, relative to the current one?
+
+- works both on GitHub and for the VuePress build
+- confusing / annoying to have things like: `../../../../myfile.md`
+- requires more updates when files are re-shuffled
+
+### Absolute
+
+Where is the other file, given the root of the repo?
+
+- works on GitHub, doesn't work for the VuePress build
+- this is much nicer: `/docs/hereitis/myfile.md`
+- if you move that file around, the links inside it are preserved (but not to it, of course)
+
+### Full
+
+The full GitHub URL to a file or directory. Used occasionally when it makes sense
+to send users to the GitHub.
+
+## Building Locally
+
+Not currently possible but coming soon! Doing so requires
+assets held in the (private) website repo, installing
+[VuePress](https://vuepress.vuejs.org/), and modifying the `config.js`.
+
+## Consistency
+
+Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
+much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/develop/docs/DOCS_README.md).

docs/README.md

@@ -7,3 +7,8 @@ Cosmos is a decentralized network of independent parallel blockchains, each powe
 The first blockchain in the Cosmos Network is the Cosmos Hub, whose native token is the Atom. Cosmos is a permission-less network, meaning that anybody can build a blockchain on it.
 
 Cosmos can interoperate with multiple other applications and cryptocurrencies. By creating a new zone, you can plug any blockchain system into the Cosmos hub and pass tokens back and forth between those zones, without the need for an intermediary.
+
+## Edit the Documentation
+
+See [this file](./DOCS_README.md) for details of the build process and
+considerations when making changes.