feat(docs): READMEs for docs, Explanation and Reference Documentation (…

…#148) (#168) * feat(docs): Add explanation structure (#148) * feat(docs): READMEs for Explanation and Reference documentation. (#148) * feat(docs): apply proposals from technical editor review (#168) Co-authored-by: Barrie Byron <[email protected]> * docs: Changes based on Technical Writer Review * fix: README introductions based on feedback * fix: Apply suggestions from code review Co-authored-by: Barrie Byron <[email protected]> Co-authored-by: Barrie Byron <[email protected]>
allinbits · Aug 18, 2021 · 184808c · 184808c
1 parent be1f211
commit 184808c
Show file tree

Hide file tree

Showing 5 changed files with 208 additions and 2 deletions.
diff --git a/docs/Explanation/README.md b/docs/Explanation/README.md
@@ -0,0 +1,66 @@
+# Explanation Documentation
+
+How to use the Cosmos Cash Explanation Documentation.
+
+- [Explanation Documentation](#explanation-documentation)
+  - [Introduction](#introduction)
+  - [Layout](#layout)
+    - [Topics](#topics)
+    - [Presentations](#presentations)
+    - [Architecture Decisions Records (ADRs)](#architecture-decisions-records-adrs)
+    - [Articles](#articles)
+  - [Discussions](#discussions)
+  - [Contributing](#contributing)
+  - [Reference](#reference)
+
+
+## Introduction
+
+This section contains **Explanation documentation** for Cosmos Cash. This content is intended to help readers with their **understanding of Cosmos Cash and related topics**. It is intended to be discursive, thoughtful, interesting, and occasionally educational. The content includes analysis and review of alternative approaches. 
+
+For further background information please see [the ADR relating to the documentation structure](./ADR/adr-002-docs-structure.md). 
+
+## Layout
+
+The scope and structure of the Explanation documentation follows this layout.
+
+### Topics
+
+Topics are discursive documents that explore some particular feature or theme.  For example, an article might investigate Decentralised Identity Documents or Self-Sovereign Identity.
+
+To contribute, create a folder in [topics](./topics) with a self-descriptive name. Add your content as needed.
+
+### Presentations
+
+The [Presentations](PRESENTATIONS.md) file describes and links to presentations about Cosmos Cash at various events. Presentations also include YouTube videos,  podcasts, interviews, and so on. 
+
+
+### Architecture Decisions Records (ADRs)
+
+ ADRs are the mechanism for contributors to raise design proposals. In turn, the ADRs explain for subsequent contributors the rationale behind Cosmos Cash design and implementation. For example, [ADR 002: Documentation Structure](./ADR/adr-002-docs-structure.md) explains why the Cosmos Cash documentation structure was chosen. 
+
+See the Architecture Decision Records (ADR) [README](./ADR/README.md) file for more details about how to raise and propose an ADR.
+
+### Articles
+
+This folder contains all articles relating to Cosmos Cash, includes papers, blog posts, and so on. For details, see [Articles README](articles/README.md).
+
+
+## Discussions
+
+The explanation content includes articles, topics, and so on, and also includes discussion on relevant channels, including [Pull Requests](https://github.com/allinbits/cosmos-cash/pulls) and [Issues](https://github.com/allinbits/cosmos-cash/issues). Important Pull Requests are listed in this document.
+
+Future: Cosmos Cash currently doesn't have a Discord or Telegram Channel. When we do, the links will be added here as well
+## Contributing
+
+* The Explanation content should be dry, clear, and terse in style.
+* All documentation is written following [Google Documentation Best Practice](https://google.github.io/styleguide/docguide/best_practices.html)
+* Autogenerate documentation from the code whenever possible.
+* Raise a PR for all documentation changes
+* Follow our [Code of Conduct](../CONTRIBUTING.md)
+
+## Reference
+
+- [Google Style Guide for Markdown](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md)
+- [Write the Docs global community](https://www.writethedocs.org/)
+- [Write the Docs Code of Conduct](https://www.writethedocs.org/code-of-conduct/#the-principles)
diff --git a/docs/Explanation/articles/README.md b/docs/Explanation/articles/README.md
@@ -1,2 +1,50 @@
-# Cosmos Cash Plans
-Cosmos Cash planning repo.
+# Articles README
+
+This folder includes all articles, papers, and so on that have been created for Cosmos Cash. 
+
+Each folder represents all of the materials and assets for a single article, including bibliographies, images, and so on. The papers themselves are written in Markdown. The Markdown files can then be published in various formats using [Pandoc](https://pandoc.org/MANUAL.html). 
+
+For publishing to PDF format, we use this [Eisvogel LaTeX template](https://github.com/Wandmalfarbe/pandoc-latex-template) to ensure a consistent look and feel. 
+
+## Technical Setup
+
+Set up your environment to manage and publish articles.
+
+
+### Prerequisites
+
+- [GNU make](https://www.gnu.org/software/make/) utility
+- [Pandoc](https://pandoc.org/installing.html)
+- [Google Inter font](https://fonts.google.com/specimen/Inter) is the Tendermint font. 
+
+### Usage
+
+- Create a folder with a self-explanatory name for the article
+- Add your content to the folder as needed.
+- Add the following front matter to the top of the Markdown document and customize as needed:
+
+```
+---
+title: "My title"
+subtitle: "My sub title"
+author: [Joe Smith]
+date: "Publish date"
+mainfont: Inter # Default Tendermint font
+fontsize: 10pt
+subject: "Cosmos Cash"
+keywords: []
+lang: "en"
+book: true
+titlepage: true
+titlepage-background: ""
+classoption: [oneside]
+page-background: "../backgrounds/BackgroundTendermint.pdf"
+footer-left: "footer"
+header-left: "header"
+footer-right: "footer"
+header-right: "header"
+---
+```
+
+- To create a new report, run the  `make buildmd` from the top-level directory NOTE: This build process is under development and won't work for the moment!!
+- To clean outputs, run `make clean`.
diff --git a/docs/Explanation/presentations.md b/docs/Explanation/presentations.md
@@ -0,0 +1,17 @@
+# Presentations
+
+
+Links to Cosmos Cash related slides, interviews, presentations.
+
+
+## Slides
+
+* [Tendermint <> ECB - May 2021](https://app.pitch.com/app/presentation/1efe6b7d-92b1-426b-ab36-eb48e0e94838/805a1f92-9d8d-47ad-9adc-10e497da08d9)
+
+
+## Interviews
+
+* [Paddy Mchale interview with Jack Zampolin - July 2021](https://www.youtube.com/watch?v=ljUEuXxuSrs) 34 minutes
+* [Alessio interview Cryptocito on CBDCs](https://www.youtube.com/watch?v=VmyO2U5qS_Y) 55 minutes
+
+## Demos
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,36 @@
+# Documentation
+
+How to use the Cosmos Cash Documentation.
+
+* [Documentation](#documentation)
+   * [Overview](#overview)
+   * [Contributing](#contributing)
+   * [Reference](#reference)
+
+## Overview
+
+In Cosmos Cash we use the  *Grand Unified Theory of Documentation* (David Laing) as described by [Divio](https://documentation.divio.com/) as a basis for our documentation strategy.
+
+This approach outlines four specific use cases for documentation:
+
+* [Tutorials](./Tutorials/README.md)
+* [How-Tos](./How-To/README.md)
+* [Explanation](./Explanation/README.md)
+* [Reference](./Reference/README.md)
+
+For further background please see [the ADR relating to the documentation structure](./ADR/adr-002-docs-structure.md). 
+
+## Contributing
+
+* Write all documentation following [Google Documentation Best Practice](https://google.github.io/styleguide/docguide/best_practices.html)
+* Generate as much documentation as possible from the code.
+* Raise a PR for all documentation changes
+* Follow our [Code of Conduct](../CONTRIBUTING.md)
+
+## Reference
+
+- [Google Style Guide for Markdown](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md)
+- [Write the Docs global community](https://www.writethedocs.org/)
+- [Write the Docs Code of Conduct](https://www.writethedocs.org/code-of-conduct/#the-principles)
+- [The good docs project](https://github.com/thegooddocsproject)
+- [Readme editor](https://readme.so/editor)
diff --git a/docs/Reference/README.md b/docs/Reference/README.md
@@ -0,0 +1,39 @@
+# Reference Documentation
+
+How to use the Cosmos Cash Reference Documentation.
+
+- [Reference Documentation](#reference-documentation)
+  - [Introduction](#introduction)
+  - [Contributing](#contributing)
+  - [Layout](#layout)
+  - [Reference](#reference)
+
+## Introduction
+
+This section contains **Reference documentation** for Cosmos Cash. [Reference Documentation](https://documentation.divio.com/reference/) is intended to be **information-oriented**. Content must allow the reader to easily navigate the content and use the content in conjunction with the code.
+
+This documentation describes the machinery, for example, classes, functions, interfaces, parameters, and so on.
+
+For further information please see [the ADR relating to the documentation structure](./ADR/adr-002-docs-structure.md). 
+## Contributing
+
+* The content must be dry, clear, and terse in style.
+* All documentation should be written following [Google Documentation Best Practice](https://google.github.io/styleguide/docguide/best_practices.html)
+* Generate as much documentation as possible from the code.
+* Raise a PR for all documentation changes
+
+## Layout
+
+Reference Documentation will come in various forms:
+
+* [Architecture diagrams](./architecture) - Diagrams must be in SVG format so that the diagrams can remain crisp and clear at any resolution or size, stored in GitHub, and version controlled. 
+* [Module specifications and designs](./MODULES.md) - By convention, module documentation in the Cosmos SDK is stored with the module itself. However, we propose that the easiest way for a new user to find documentation is to store the documentation at the root `docs` folder. To accomodate this module, the documentation will follow the existing convention, but the content will be reference from this section.
+* **Code-level documentation** - The text that is part of the code and is used to auto-generate the documentation from the code.
+* **API reference** - Including REST and gRPC endpoints.
+* [Glossary](,.GLOSSARY.md) - a dictionary of domain-relevant terms. This glossary can be used in conjunction with the [Cosmos Network Glossary](https://v1.cosmos.network/glossary).
+
+## Reference
+
+- [Google Style Guide for Markdown](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md)
+- [Write the Docs global community](https://www.writethedocs.org/)
+- [Write the Docs Code of Conduct](https://www.writethedocs.org/code-of-conduct/#the-principles)