docs: contribution guidelines (#1906)

Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Signed-off-by: Giovanni Liva <giovanni.liva@dynatrace.com>
Co-authored-by: Giovanni Liva <giovanni.liva@dynatrace.com>

docs/CONTRIBUTING.md

@@ -25,11 +25,11 @@ We were all new to this once and are happy to help you!
 
 ## Guidelines for Contributing
 
-Please check [Contribution Guidelines](content/en/contribute/docs/contribution-guidelines/_index.md).
+Please check [Contribution Guidelines](content/en/contribute/docs/contrib-guidelines-docs/_index.md).
 
 ## Building the Documentation Locally
 
-Please check [Building the Documentation Locally](content/en/contribute/docs/local-building/index.md).
+Please check [Building the Documentation Locally](content/en/contribute/docs/local-building/_index.md).
 
 ## Interacting with github
 

docs/content/en/contribute/docs/contrib-guidelines-docs/_index.md

@@ -0,0 +1,89 @@
+---
+title: Contribution guidelines for documentation
+description: Guidelines for contributing towards Keptn Lifecycle Toolkit
+weight: 300
+---
+
+The [Contribution Guidelines](../../general/contrib-guidelines-gen) page
+contains guidelines that are relevant
+for both documentation and software contributions.
+This page lists additional guidelines
+that are relevant only to documentation
+
+## Guidelines for contributing
+
+* Keep your language clean and crisp.
+  We do not have an official *Style Guide* for Keptn but the
+  [Google developer documentation style guide](https://developers.google.com/style)
+  is a good general reference.
+
+* Use topic sentences for sections and paragraphs.
+  When reading a well-written technical document,
+  you should be able to read the first sentence in each paragraph
+  and especially in each section to get an idea of what might follow.
+
+  Good oral presentations commonly begin with a "set-up"
+  where they describe a problem
+  and then proceed to tell how to fix that problem.
+  When using oral presentations as source material,
+  it is important to rewrite the text
+  so that the actual subject of discussion comes first.
+
+* Avoid using FAQ's in documentation.
+  In general, they say "here is some miscellaneous information
+  that I was too lazy to organize logically for you."
+  In rare occasions, they may be appropriate,
+  such as if you need a quick reference to a large, complicated document
+  and include links to detailed documentation about the topic.
+
+* We are attempting to avoid duplicated information across the doc set,
+  especially for information that is expected to change.
+  For example, information about supported Kubernetes versions
+  and the command sequence to install KLT should usually be done
+  as references to the official installation section of the docs.
+
+  For usability considerations, we make the following exceptions:
+
+  * The main `README.md` file for the lifecycle-controller repository
+    includes this basic information as well as a link
+    to the full installation documentation which has more details.
+  * The Getting Started Guide also includes this information
+    for the same reason.
+
+* `markdownlint` enforces limits on line length.
+  Links to other documents are exempted from this limit
+  but, if a line has words before and after the long string,
+  `markdownlint` fails.
+  A good practice is to just code all links on their own page.
+  So, instead of coding:
+
+  ```shell
+  The [Other section](long-link-to-section) page
+  ...
+  ```
+
+  you should code the following,
+  unless the link is so short
+  that you are sure it will not violate the line-length rules::
+
+  ```shell
+  The
+  [Other section](long-link-to-section)
+  page
+  ...
+  ```
+
+* Always build the documentation locally to check the formatting
+  and verify that all links are working properly.
+  See [Build Documentation Locally](../local-building)
+  for details.
+
+* Always run the following to fix most markdown issues in your PR
+  and identify issues that can not be fixed automatically:
+
+  ```shell
+  make markdownlint-fix
+  ```
+
+  See [Markdownlint](../linter-requirements/#markdownlint)
+  for details.

docs/content/en/contribute/docs/local-building/index.md → docs/content/en/contribute/docs/local-building/_index.md

@@ -21,25 +21,19 @@ To set up a local Docsy build:
    * [Install on Linux](https://docs.docker.com/desktop/install/linux-install/)
    * [Install on Windows](https://docs.docker.com/desktop/install/windows-install/)
 
-1. Build the Keptn Docsy repo:
+1. Execute the following command from the `docs` folder of your clone:
 
    ```shell
-   make build
+   make server
    ```
 
+   It will continue running in its own shell.
+
    > **Note**
    To utilize the `Makefile`, you must have GNU **make**
    available on your local machine.
    Versions are available for all the usual Operating Systems.
 
-1. Execute the following command from the `docs` folder of your clone:
-
-   ```shell
-   make server
-   ```
-
-   It will continue running in its own shell.
-
 1. Start contributing!
 Note that Hugo updates the rendered documentation each time you write the file.
 

docs/content/en/contribute/docs/contribution-guidelines/_index.md → docs/content/en/contribute/general/contrib-guidelines-gen/_index.md

@@ -1,22 +1,25 @@
 ---
 title: Contribution Guidelines
-description: Guidelines for contributing towards Keptn Lifecycle Toolkit
-weight: 300
+description: Guidelines for contributing to Keptn Lifecycle Toolkit
+weight: 50
 ---
 
 Before using the **Keptn Lifecycle Toolkit**
 as a contributor to the Keptn Lifecycle Toolkit repository,
 it is expected that you comply with the guidelines while
 making contributions towards the repository.
 
+These guidelines are appropriate for both software and documentation.
+For additional guidelines that are relevant only to documentation, see
+[Contribution guidelines for documentation](../../docs/contrib-guidelines-docs).
+
 ## Guidelines for contributing
 
 * Always fork the repository then clone that fork to your local system
   rather than clone `main` directly.
   Keptn, like most open source projects,
   severely restricts who can push changes directly to the `main` branch
   to protect the integrity of the repository.
-* Keep your language clean and crisp.
 * Smaller PR's are easier to review and so generally get processed more quickly;
   when possible, chunk your work into smallish PR's.
   However, we recognize that documentation work sometimes requires larger PRs,
@@ -30,7 +33,7 @@ making contributions towards the repository.
   This helps reviewers understand each commit
   and provides a good history after the PR is merged.
 * If your PR is not reviewed in a timely fashion,
-  feel free to post a gentle reminder to the `#keptn-docs` Slack channel.
+  feel free to post a gentle reminder to the `#keptn-help-contributing` Slack channel.
 * Resolve review comments and suggestions promptly.
 
 If you see a problem and are unable to fix it yourself