Updated the Contributor Guide

website/community/_index.md

@@ -25,3 +25,6 @@ The recordings are published on the [Gardener Project YouTube channel](https://w
 <p style="margin-top:30px"><strong>Google Calendar</strong></p>
 <iframe src="https://calendar.google.com/calendar/embed?src=gardener.cloud.community%40gmail.com&ctz=Europe%2FBerlin" style="border: 0;margin-bottom:30px" width="800" height="600" frameborder="0" scrolling="no"></iframe>
 
+### Presenting a Topic
+
+If there is a topic you would like to present, message us in our [#gardener](https://kubernetes.slack.com/messages/gardener) slack channel or get in touch with [Jessica Katz](mailto:[email protected]).

website/documentation/contribute/10_code/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Code
+title: Contributing Code
 url: /contribute/code/
 ---
 

website/documentation/contribute/20_documentation/10_organisation/_index.md

@@ -14,7 +14,7 @@ The Gardener project implements the *documentation-as-code* paradigm. Essentiall
 
 Documentation that can be affiliated to component is hosted and maintained in the component repository.
 
-A recommended template for organizing documentation sources is to place them all in a `docs` folder and organize it there per role activity. For example:
+A good way to organize your documentation is to place it in a 'docs' folder and create separate subfolders per role activity. For example:
 
 ```
 repositoryX
@@ -27,7 +27,7 @@ repositoryX
    |_ deployment
 ```
 
-Do not use folders just because they are in the template. Stick to the predefined roles and corresponding activities for naming convention. A system makes it easier to maintain and get oriented.
+Do not use folders just because they are in the template. Stick to the predefined roles and corresponding activities for naming convention. A system makes it easier to maintain and get oriented. While recommended, this is not a mandatory way of organizing the documentation.
 
 - User: `usage`
 - Operator: `operations`
@@ -41,11 +41,11 @@ Do not use folders just because they are in the template. Stick to the predefine
 The Gardener website is one of the multiple optional publishing channels where the source material might end up as documentation. We use docforge and automated integration and publish process to enable transparent change
 management. 
 
-To have documentation published on the website it is necessary to use the docforge manifests available at [gardener/documentation/.docforge] adn register a reference to your documentation.
+To have documentation published on the website it is necessary to use the docforge manifests available at [gardener/documentation/.docforge](https://github.com/gardener/documentation/tree/master/.docforge) and register a reference to your documentation.
 
 {{% alert color="info" title="Note" %}} 
 This is work in progress and we are transitioning to a more transparent way of integrating component documentation. This guide will be updated as we progress.
 {{% /alert %}}
 
 These manifests describe a particular publishing goal, i.e. using Hugo to publish on the website, and you will find out that they contain Hugo-specific front-matter properties.
-Consult with the documentation maintainers for details. Use the gardener channel in slack or open a PR.
+Consult with the documentation maintainers for details. Use the gardener channel in [slack](https://kubernetes.slack.com/messages/gardener) or [open a PR](https://github.com/gardener/documentation/pulls).

website/documentation/contribute/20_documentation/20_formatting_guide/_index.md

@@ -4,11 +4,11 @@ title: Formatting Guide
 
 This page gives writing formatting guidelines for the Gardener documentation. For style guidelines, see the [Style Guide](../40_style_guide/_index.md).
 
-These are guidelines, not rules. Use your best judgment, and feel free to
-propose changes to this document in a pull request.
+These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
 
 * [Formatting of Inline Elements](#formatting-of-inline-elements)
 * [Code Snippet Formatting](#code-snippet-formatting)
+* [Related Links](#related-links)
 
 ## Formatting of Inline Elements
 
@@ -118,14 +118,14 @@ Another thing to keep in mind is that markdown links do not work in [shortcodes]
 
 ## Code Snippet Formatting
 
-### Don't include the command prompt
+### Don't Include the Command Prompt
 
 |  Do  | Don't |
 |:---|:---|
 | `kubectl get pods`  | `$ kubectl get pods` |
 
 
-### Separate commands from output
+### Separate Commands from Output
 
 <code>
 Verify that the pod is running on your chosen node:
@@ -154,7 +154,10 @@ kubectl describe pod <pod-name>
 
 </code>
 
-
 ### Versioning Kubernetes examples
 
 Make code examples and configuration examples that include version information consistent with the accompanying text. Identify the Kubernetes version in the **Prerequisites** section.
+
+## Related links
+* [Style Guide](../40_style_guide/_index.md)
+* [Contributors Guide](../_index.md)

website/documentation/contribute/20_documentation/25_markup/_index.md

@@ -2,7 +2,7 @@
 title: Markdown
 ---
 
-Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown 
+Hugo uses [Markdown](https://www.markdownguide.org/) for its simple content format. However, there are a lot of things that Markdown 
 doesn't support well. You could use pure HTML to expand possibilities. A typical example is reducing
 the original dimensions of an image.
 
@@ -12,4 +12,8 @@ a publishing platform mechanisms, such as Hugo's layouts. Considering that the s
 might be published by multiple platforms you should be considerate in using markup that may bind it 
 to a particular one.
 
-We support the use of certain shortcodes. You can find more about the currently supported shortcodes and their documentation [here](../30_shortcodes/_index.md).
+For the same reason, avoid inline scripts and styles in your content. If you absolutely need to use them and they are not working as expected, please create a documentation issue and describe your case.
+
+{{% alert color="info" title="Tip" %}}
+Markdown is great for its simplicity but may be also constraining for the same reason. Before looking at HTML to make up for that, first check the [shortcodes](https://github.com/gardener/documentation/blob/master/website/documentation/contribute/20_documentation/30_shortcodes/_index.md) for alternatives.
+{{% /alert %}}

website/documentation/contribute/20_documentation/40_style_guide/_index.md

@@ -3,11 +3,11 @@ Title: Style Guide
 ---
 This page gives writing style guidelines for the Gardener documentation. For formatting guidelines, see the [Formatting Guide](../20_formatting_guide/_index.md).
 
-These are guidelines, not rules. Use your best judgment, and feel free to
-propose changes to this document in a pull request.
+These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a Pull Request.
 
 * [Structure](#structure)
 * [Language and Grammar](#language-and-grammar)
+* [Related Links](#related-links)
 
 ## Structure
 
@@ -28,67 +28,87 @@ See the [Contributors Guide](https://github.com/gardener/documentation/blob/mast
 
 When creating a topic, you will need to follow a certain structure. A topic generally comprises of, in order:
 
-* [Metadata](#metadata) (Specific for `.md` files in Gardener) - Additional information about the topic.
+* [Metadata](#front-matter) (Specific for `.md` files in Gardener) - Additional information about the topic
 
-* Title - A short, descriptive name for the topic.
+* Title - A short, descriptive name for the topic
 
-* Content - The main part of the topic. It contains all the information relevant to the user.
+* Content - The main part of the topic. It contains all the information relevant to the user
     * Concept content: [Overview, Relevant headings](concept_template.md)
     * Task content: [Overview, Prerequisites, Steps, Result](task_template.md)
     * Reference content: [Relevant headings](reference_template.md)
 
-* Related Links (Optional) - A part after the main content that contains links that are not a part of the topic, but are still connected to it. 
+* Related Links (Optional) - A part after the main content that contains links that are not a part of the topic, but are still connected to it
 
 You can use the provided content description files as a template for your own topics.
 
-### Metadata
+### Front Matter
 
-Metadata is information housed in a specific section of the `.md` files used for the Gardener documentation. It can contain:
-* Title - A short, descriptive name for the topic.
-* Description - A succint summary of the topic's content. Must not include the title or repeat content from the topic.
-* Other elements such as weight, creation date, author and tags.
+[Front matter](https://gohugo.io/content-management/front-matter) is metadata applied at the head of each content Markdown file. It is used to instruct the static site generator build process. The format is YAML and it must be enclosed in leading and trailing comment dashes (`---`).
 
 Sample codeblock:
-```
+```yaml
 ---
-Title: 
-Description:
-Weight: 
+title: Getting Started
+Description: Guides to get you accustomed with Gardener
+Weight: 10
 ---
 ```
 
+There are a number of [predefined](https://gohugo.io/content-management/front-matter#predefined) front matter properites, but not all of them are considered by the layouts developed for the website. The most essential ones to consider are:
+- `title` the content title that will be used as page title and in navigation structures.
+- `weight` a positive integer number that controls the ordering of the content in navigation structures.
+- `description` describes the content. For some content types such as documentation guides, it may be rendered in the UI.
+- `url` if specified, it will override the default url constructed from the file path to the content. Make sure the url you specify is consistent and meaningful. Prefer short paths. Do not provide redundant URLs!
+- `categories` specifies the type of user the topic is aimed towards. Currently only used in the public website.
+  ```
+  categories:
+  - Users
+  - Operators
+  - Developers
+  ```
+
 While this section will be automatically generated if your topic has a title header, adding more detailed information helps other users, developers and technical writers better sort, classify and understand the topic. 
 
 By using a metadata section you can also skip adding a title header or overwrite it in the navigation section. 
 
+### Alerts
+
+If you want to add a note, tip, or a warning to your topic, use the templates provides in the [Shortcodes](../30_shortcodes/_index.md#alert) documentation.
+
+### Images
+
+If you want to add an image to your topic, it is recommended to follow the guidelines outlined in the [Images](../45_images/_index.md) documentation.
+
 ### General Tips
 
-* Try to create a succint title and an informative description for your topics.
-* If a topic feels too long, it might be better to split it into a few different ones.
-* Avoid having have more than ten steps in one a task topic.
-* When writing a tutorial, link the tasks used in it instead of copying their content.
+* Try to create a succint title and an informative description for your topics
+* If a topic feels too long, it might be better to split it into a few different ones
+* Avoid having have more than ten steps in one a task topic
+* When writing a tutorial, link the tasks used in it instead of copying their content
 
 ## Language and Grammar
 
 ### Language
-* Gardener documentation uses US English. 
-* Keep it simple and use words that non-native English speakers are also familiar with.
-* Use the [Merriam-Webster Dictionary](https://www.merriam-webster.com/) when checking the spelling of words.
+* Gardener documentation uses US English
+* Keep it simple and use words that non-native English speakers are also familiar with
+* Use the [Merriam-Webster Dictionary](https://www.merriam-webster.com/) when checking the spelling of words
 
 ### Writing Style
 
-* Write in a conversational manner and use simple present tense. 
-* Be friendly and refer to the person reading your content as "you", instead of standard terms such as "user". 
-* Use an active voice - make it clear who is performing the action.
+* Write in a conversational manner and use simple present tense
+* Be friendly and refer to the person reading your content as "you", instead of standard terms such as "user"
+* Use an active voice - make it clear who is performing the action
 
 ### Creating Titles and Headers
 
-* Use [title case](https://titlecaseconverter.com/words-to-capitalize/) when creating titles or headers.
-* Avoid adding additional formatting to the title or header.
-* Concept and reference topic titles should be simple and succint.
-* Task and tutorial topic titles begin with a verb.
+* Use [title case](https://titlecaseconverter.com/words-to-capitalize/) when creating titles or headers
+* Avoid adding additional formatting to the title or header
+* Concept and reference topic titles should be simple and succint
+* Task and tutorial topic titles begin with a verb
 
 ## Related links
 * [Formatting Guide](../20_formatting_guide/_index.md)
-* [Contributors Guide](https://github.com/gardener/documentation/blob/master/website/documentation/contribute/_index.md)
+* [Contributors Guide](../_index.md)
+* [Shortcodes](../30_shortcodes/_index.md)
+* [Images](../45_images/_index.md)
 * [SAPterm](https://www.sapterm.com/)

website/documentation/contribute/20_documentation/40_style_guide/concept_template.md

@@ -4,6 +4,7 @@ Description: Describes the contents of a concept topic
 ---
 
 # Concept Title
+(the topic title can also be placed in the frontmatter)
 
 ## Overview
 This section provides an overview of the topic and the information provided in it. 
@@ -12,7 +13,7 @@ This section provides an overview of the topic and the information provided in i
 This section gives the user all the information needed in order to understand the topic.
 
 ### Relevant subheading
-This adds information that belongs to the topic discussed in the parent heading
+This adds additional information that belongs to the topic discussed in the parent heading.
 
 ## Relevant heading 2
 This section gives the user all the information needed in order to understand the topic.

website/documentation/contribute/20_documentation/40_style_guide/reference_template.md

@@ -4,6 +4,7 @@ Description: Describes the contents of a reference topic
 ---
 
 # Topic Title
+(the topic title can also be placed in the frontmatter)
 
 ## Content
 This section gives the user all the information needed in order to understand the topic.

website/documentation/contribute/20_documentation/40_style_guide/task_template.md

@@ -4,6 +4,7 @@ Description: Describes the contents of a task topic
 ---
 
 # Task Title
+(the topic title can also be placed in the frontmatter)
 
 ## Overview
 This section provides an overview of the topic and the information provided in it. 
@@ -13,12 +14,19 @@ This section provides an overview of the topic and the information provided in i
 * Prerequisite 2
 
 ## Steps
+Avoid nesting headings directly on top of each other with no text inbetween.
+1. Describe step 1 here
+1. Describe step 2 here
+
+### You can use smaller sections within sections for related tasks
+Avoid nesting headings directly on top of each other with no text inbetween.
 1. Describe step 1 here
 1. Describe step 2 here
 
 ## Result
-Screenshot of the final status once all the steps have been followed. 
+Screenshot of the final status once all the steps have been completed. 
 
 ## Related Links
+Provide links to other relevant topics, if applicable. Once someone has completed these steps, what might they want to do next?
 * [Link 1]()
 * [Link 2]()