docs: update contribute/docs section (#3366)

Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
keptn · Apr 2, 2024 · 95eb17e · 95eb17e
1 parent 016dc07
commit 95eb17e
Show file tree

Hide file tree

Showing 7 changed files with 50 additions and 16 deletions.
diff --git a/docs/docs/contribute/docs/contrib-guidelines-docs.md b/docs/docs/contribute/docs/contrib-guidelines-docs.md
@@ -44,7 +44,9 @@ that are relevant only to documentation.
   as references to the official installation section of the docs.
 
     For usability considerations, we have a few exceptions to this rule
-    for the main `README.md` file and the [Getting Started Guide](../../getting-started/index.md).
+    for the main `README.md` file and the exercises in the
+    [Get Started](../../getting-started/index.md)
+    section.
 
 * When you want to display a sample file that exists in the repository,
   use the `include <file-path>` shortcode syntax

diff --git a/docs/docs/contribute/docs/index.md b/docs/docs/contribute/docs/index.md
@@ -4,10 +4,38 @@ comments: true
 
 # Documentation contributions
 
-This section is under development.
-Contents are not complete,
-but all material here has been reviewed for technical accuracy.
+Keptn documentation source is stored in the same repository
+as Keptn software and test code
+and is developed using the same practices used for software
+and described in the
+[General information](../general/index.md) section
+of this *Contributing Guide*.
 
-Keptn software and documentation
-is developed and maintained by the Keptn community.
-We invite you to join us.
+The pages in this section augment the "General" information
+with information that is specific to the documentation:
+
+- [Contribution guidelines for documentation](contrib-guidelines-docs.md)
+  augments the general
+  [Contribution Guidelines](../general/contrib-guidelines-gen.md)
+  with guidelines that are only relevant to documentation.
+- [Build Documentation Locally](local-building.md)
+  tells how to build the documentation locally
+  so you can check the formatting, readability, and links
+  in your local branch before you push the new content.
+- [Markdownlint](markdownlint.md) provides information
+  about the linter we use to check the quality of the coding
+  in all `.md` files in the repository.
+- [Source file structure](source-file-structure.md)
+  describes the sections of the documentation
+  and how the structure of the published documentation is defined.
+- [Coding the docs](code-docs.md) gives some hints
+  about the markdown practices used for the Keptn documentation.
+- [Spell checker](spell-check.md) describes the spell checker we use
+  and gives instructions for resolving errors it finds.
+- [Blogs](blog.md) explains the extra steps required
+  to contribute a blog to the Keptn page.
+- [Published doc structure](publish.md) explains
+  the branches (`stable` and `latest`) for the published documentation.
+- [Word list](word-list.md) provides some information about the proper
+  use of Keptn and Kubernetes terms in the documentation
+  as well as links to other documents with more comprehensive word lists.
diff --git a/docs/docs/contribute/docs/markdownlint.md b/docs/docs/contribute/docs/markdownlint.md
@@ -27,6 +27,12 @@ run the following on your local branch:
 make markdownlint
 ```
 
+Markdown includes an auto-fix option that you can run on your local branch
+to resolve many issues such as extra spaces
+and notify you of errors it can not fix automatically.
+You should always run this command before pushing a commit
+and resolve any errors it reports.
+
 To use the auto-fix option, run:
 
 ```shell

diff --git a/docs/docs/contribute/docs/publish.md b/docs/docs/contribute/docs/publish.md
@@ -2,7 +2,7 @@
 comments: true
 ---
 
-# Published Doc Structure
+# Published doc structure
 
 New writing goes to the `main` branch and can be viewed on the Keptn website under the `latest` version.
 We have staging and production levels for our documentation which are as follows:

diff --git a/docs/docs/contribute/docs/source-file-structure.md b/docs/docs/contribute/docs/source-file-structure.md
@@ -2,7 +2,7 @@
 comments: true
 ---
 
-# Source File Structure
+# Source file structure
 
 The source files for the Keptn documentation
 are stored in the same GitHub repository as the source code for the software.
@@ -164,8 +164,6 @@ See
 [Published Doc Structure](./publish.md)
 for information about the branches where the documentation is published.
 
-All files in the directories are built.
-
 The order in which the files are displayed
 is determined by their order in the `nav` field
 of the `mkdocs.yml` file.

diff --git a/docs/docs/contribute/docs/spell-check.md b/docs/docs/contribute/docs/spell-check.md
@@ -2,7 +2,7 @@
 comments: true
 ---
 
-# Spell Checker
+# Spell checker
 
 All PRs that are pushed to a Keptn repository
 are run through a spell checker that is based on the

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -228,12 +228,12 @@ nav:
           - docs/contribute/docs/index.md
           - Contribution guidelines for documentation: docs/contribute/docs/contrib-guidelines-docs.md
           - Build Documentation Locally: docs/contribute/docs/local-building.md
-          - Using markdownlint: docs/contribute/docs/markdownlint.md
-          - Source File Structure: docs/contribute/docs/source-file-structure.md
+          - Markdownlint: docs/contribute/docs/markdownlint.md
+          - Source file structure: docs/contribute/docs/source-file-structure.md
           - Coding the docs: docs/contribute/docs/code-docs.md
-          - Spell Checker: docs/contribute/docs/spell-check.md
+          - Spell checker: docs/contribute/docs/spell-check.md
           - Blogs: docs/contribute/docs/blog.md
-          - Published Doc Structure: docs/contribute/docs/publish.md
+          - Published doc structure: docs/contribute/docs/publish.md
           - Word list: docs/contribute/docs/word-list.md
   - Blog:
       - blog/index.md