From 25bf6ce1a32b15c870c3dadff861999eef8a4896 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 1 Sep 2023 02:56:46 -0700 Subject: [PATCH] docs: contribution guidelines (#1906) Signed-off-by: Meg McRoberts Signed-off-by: Giovanni Liva Co-authored-by: Giovanni Liva --- docs/CONTRIBUTING.md | 4 +- .../docs/contrib-guidelines-docs/_index.md | 89 +++++++++++++++++++ .../local-building/{index.md => _index.md} | 14 +-- .../contrib-guidelines-gen}/_index.md | 11 ++- 4 files changed, 102 insertions(+), 16 deletions(-) create mode 100644 docs/content/en/contribute/docs/contrib-guidelines-docs/_index.md rename docs/content/en/contribute/docs/local-building/{index.md => _index.md} (97%) rename docs/content/en/contribute/{docs/contribution-guidelines => general/contrib-guidelines-gen}/_index.md (82%) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 78327e3b07..4f2690e765 100644 --- a/docs/CONTRIBUTING.md +++ b/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 diff --git a/docs/content/en/contribute/docs/contrib-guidelines-docs/_index.md b/docs/content/en/contribute/docs/contrib-guidelines-docs/_index.md new file mode 100644 index 0000000000..73659cacbc --- /dev/null +++ b/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. diff --git a/docs/content/en/contribute/docs/local-building/index.md b/docs/content/en/contribute/docs/local-building/_index.md similarity index 97% rename from docs/content/en/contribute/docs/local-building/index.md rename to docs/content/en/contribute/docs/local-building/_index.md index ee2d774137..73d360856a 100644 --- a/docs/content/en/contribute/docs/local-building/index.md +++ b/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. diff --git a/docs/content/en/contribute/docs/contribution-guidelines/_index.md b/docs/content/en/contribute/general/contrib-guidelines-gen/_index.md similarity index 82% rename from docs/content/en/contribute/docs/contribution-guidelines/_index.md rename to docs/content/en/contribute/general/contrib-guidelines-gen/_index.md index c85703db43..ca4aa2dec9 100644 --- a/docs/content/en/contribute/docs/contribution-guidelines/_index.md +++ b/docs/content/en/contribute/general/contrib-guidelines-gen/_index.md @@ -1,7 +1,7 @@ --- 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** @@ -9,6 +9,10 @@ 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 @@ -16,7 +20,6 @@ making contributions towards the repository. 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