Update Docs (#1528)

* Update docs 1. Simplify installation steps 2. Remove 'usage' section and promote its subsections to main sections 3. Add 'next step' to tutorial 4. Remove obsolete Helm instructions page 5. Remove redundant prefix in page titles 6. Update copyright info. in footer Signed-off-by: Ivan Sim <ivan.sim@kasten.io> * Add documentation style guide Signed-off-by: Ivan Sim <ivan.sim@kasten.io> * Address feedback Signed-off-by: Ivan Sim <ivan.sim@kasten.io> * Address Pavan's feedback Signed-off-by: Ivan Sim <ivan.sim@kasten.io> * Update docs/README.md Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com> Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
kanisterio · Jul 7, 2022 · 0c3c45d · 0c3c45d
1 parent 3439902
commit 0c3c45d
Show file tree

Hide file tree

Showing 17 changed files with 127 additions and 497 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,41 @@
+## Kanister Documentation
+
+This folder contains the source of the Kanister documentation at
+https://docs.kanister.io
+
+## Building The Source
+
+The contents are written in the
+[reStructuredText](https://docutils.sourceforge.io/rst.html) format.
+
+To rebuild the documentation, run this command from the project root folder:
+
+```sh
+make docs
+```
+
+The `docs` target uses the `ghcr.io/kanisterio/docker-sphinx` public image to
+generate the HTML documents and store them in your local `/docs/_build/html`
+folder.
+
+## Language, Grammar, and Tone
+
+When updating the documentation content, please follow these guidelines on the
+language, grammar, and tone style:
+
+* Documentation should be written in English.
+* Prefer an active voice and present tense when possible.
+* Use simple and direct language.
+* Use gender-neutral language.
+* Avoid personal pronouns ("I," "we," "us," "our," and "ours").
+* Address the reader as "you" instead of "we".
+* Do not use Latin phrases.
+* Avoid jargon and idioms.
+* If using acronyms, ensure they are clearly defined in the same document.
+* If using an abbreviation, spell it out the first time it is used in the document unless it is commonly known. (example: TCP/IP)
+* When referring to a Kubernetes Group (SIG, WG, or UG) do not use the hyphenated form unless it is for a specific purpose such as a file-name or URI.
+
+These guidelines are derived from the
+[cheatsheet](https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md#cheatsheet-content-design-formatting-and-language)
+in the Kubernetes community style guide. Take a look at some of their examples
+[here](https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md#language-grammar-and-tone).
diff --git a/docs/architecture.rst b/docs/architecture.rst
@@ -1,9 +1,9 @@
 .. _architecture:
 
-Kanister Architecture Overview
-******************************
+Architecture
+************
 
-.. contents:: Kanister Architecture Overview
+.. contents:: Architecture
   :local:
 
 The design of Kanister follows the operator pattern. This means

diff --git a/docs/conf.py b/docs/conf.py
@@ -54,7 +54,7 @@
 
 # General information about the project.
 project = 'Kanister'
-copyright = '2017-2019, Kanister'
+copyright = '2017-2022, Kanister'
 author = 'Kanister'
 
 # The version info for the project you're documenting, acts as replacement for

diff --git a/docs/functions.rst b/docs/functions.rst
@@ -1,7 +1,7 @@
 .. _functions:
 
-Kanister Functions
-******************
+Functions
+*********
 
 Kanister Functions are written in go and are compiled when building the
 controller. They are referenced by Blueprints phases. A Kanister Function

diff --git a/docs/helm.rst b/docs/helm.rst
diff --git a/docs/helm_instructions/create_profile.rst b/docs/helm_instructions/create_profile.rst
diff --git a/docs/helm_instructions/elasticsearch_instructions.rst b/docs/helm_instructions/elasticsearch_instructions.rst
diff --git a/docs/helm_instructions/mongodb_instructions.rst b/docs/helm_instructions/mongodb_instructions.rst
diff --git a/docs/helm_instructions/mysql_instructions.rst b/docs/helm_instructions/mysql_instructions.rst