diff --git a/docs/docs/contribute/docs/contrib-guidelines-docs.md b/docs/docs/contribute/docs/contrib-guidelines-docs.md index 3197d32d93..af7f97eb48 100644 --- 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 ` shortcode syntax diff --git a/docs/docs/contribute/docs/index.md b/docs/docs/contribute/docs/index.md index 05d74d281c..00b7de616a 100644 --- 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 index d0c516e102..7eec3e0be9 100644 --- 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 index fc8aaf20ad..dd4484eb3a 100644 --- 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 index f758217108..23b9a86413 100644 --- 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 index 8a09d00e4a..1c0a66f0da 100644 --- 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 index cfdce55cd9..d8711336da 100644 --- 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