This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Contributing Documentation

You are welcome to contribute documentation to Gardener.

The following rules govern documentation contributions:

  • Contributions must be licensed under the Creative Commons Attribution 4.0 International License
  • You need to sign the Contributor License Agreement. We are using CLA assistant providing a click-through workflow for accepting the CLA. For company contributors additionally the company needs to sign a corporate license agreement. See the following sections for details.

1 - Working with Images

Using images on the website has to contribute to the aestethics and comprehendability of the materials, with uncompromised experience when loading and browsing pages. That concerns crisp clear images, their consistent layout and color scheme, dimensions and aspect ratios, flicker-free and fast loading or the feeling of it, even on unreliable mobile networks and devices.

Image Production Guidelines

A good, detailed reference for optimal use of images for the web can be found at web.dev’s Fast Load Times topic. The following summarizes some key points plus suggestions for tools support.

You are strongly encouraged to use vector images (SVG) as much as possible. They scale seamlessly without compromising the quality and are easier to maintain.

If you are just now starting with SVG authoring, here are some tools suggestions: Figma (online/Win/Mac), Sketch (Mac only).

For raster images (JPG, PNG, GIF), consider the following requirements and choose a tool that enables you to conform to them:

  • Be mindful about image size, the total page size and loading times.
  • Larger images (>10K) need to support progressive rendering. Consult with your favorite authoring tool’s documentation to find out if and how it supports that.
  • The site delivers the optimal media content format and size depending on the device screen size. You need to provide several variants (large screen, laptop, tablet, phone). Your authoring tool should be able to resize and resample images. Always save the largest size first and then downscale from it to avoid image quality loss.

If you are looking for a tool that conforms to those guidelines, IrfanView is a very good option.

Screenshots can be taken with whatever tool you have available. A simple Alt+PrtSc (Win) and paste into an image processing tool to save it does the job. If you need to add emphasized steps (1,2,3) when you describe a process on a screeshot, you can use Snaggit. Use red color and numbers. Mind the requirements for raster images laid out above.

Diagrams can be exported as PNG/JPG from a diagraming tool such as Visio or even PowerPoint. Pick whichever you are comfortable with to design the diagram and make sure you comply with the requirements for the raster images production above. Diagrams produced as SVG are welcome too if your authoring tool supports exporting in that format. In any case, ensure that your diagrams “blend” with the content on the site - use the same color scheme and geometry style. Do not complicate diagrams too much. The site also supports Mermaid diagrams produced with markdown and rendered as SVG. You don’t need special tools for them, but for more complex ones you might want to prototype your diagram wth Mermaid’s online live editor, before encoding it in your markdown. More tips on using Mermaid can be found in the Shortcodes documentation.

Using Images in Markdown

The standard for adding images to a topic is to use markdown’s ![caption](image-path). If the image is not showing properly, or if you wish to serve images close to their natural size and avoid scaling, then you can use HTML5’s <picture> tag.

Example:

<picture>
    <!-- default, laptop-width-L max 1200px -->
    <source srcset="https://github.tools.sap/kubernetes/documentation/tree/master/website/documentation/015-tutorials/my-guide/images/overview-XL.png"
            media="(min-width: 1000px)">
    <!-- default, laptop-width max 1000px -->
    <source srcset="https://github.tools.sap/kubernetes/documentation/tree/master/website/documentation/015-tutorials/my-guide/images/overview-L.png"
            media="(min-width: 1400px)">
    <!-- default, tablets-width max 750px -->
    <source srcset="https://github.tools.sap/kubernetes/documentation/tree/master/website/documentation/015-tutorials/my-guide/images/overview-M.png"
            media="(min-width: 750px)">
    <!-- default, phones-width max 450px -->
    <img src="https://github.tools.sap/kubernetes/documentation/tree/master/website/documentation/015-tutorials/my-guide/images/overview.png" />
</picture>

When deciding on image sizes, consider the breakpoints in the example above as maximum widths for each image variant you provide. Note that the site is designed for maximum width 1200px. There is no point to create images larger than that, since they will be scaled down.

For a nice overview on making the best use of responsive images with HTML5, please refer to the Responsive Images guide.

2 - Adding Already Existing Documentation

Overview

In order to add GitHub documentation to the website that is hosted outside of the main repository, you need to make changes to the central manifest. You can usually find it in the <organization-name>/<repo-name>/.docforge/ folder, for example gardener/documentation/.docforge.

Sample codeblock:

- dir: machine-controller-manager
  structure:
  - file: _index.md
    frontmatter:
      title: Machine Controller Manager
      weight: 1
      description: Declarative way of managing machines for Kubernetes cluster
    source: https://github.com/gardener/machine-controller-manager/blob/master/README.md
  - fileTree: https://github.com/gardener/machine-controller-manager/tree/master/docs

This short code snippet adds a whole repository worth of content and contains examples of some of the most important elements:

  • - dir: <dir-name> - the name of the directory in the navigation path
  • structure: - required after using dir; shows that the following lines contain a file structure
  • - file: _index.md - the content will be a single file; also creates an index file
  • frontmatter: - allows for manual setting/overwriting of the various properties a file can have
  • source: <link> - where the content for the file element is located
  • - fileTree: <link> - the content will be a whole folder; also gives the location of the content

Check the Notes and Tips section for useful advice when making changes to the manifest files.

Adding Existing Documentation

You can use the following templates in order to add documentation to the website that exists in other GitHub repositories.

Adding a Single File

You can add a single topic to the website by providing a link to it in the manifest.

- dir: <dir-name>
  structure:
  - file: <file-name>
    frontmatter:
      title: <topic-name>
      description: <topic-description>
      weight: <weight>
    source: https://github.com/<path>/<file>
Example
- dir: dashboard
  structure:
  - file: _index.md
    frontmatter:
      title: Dashboard
      description: The web UI for managing your projects and clusters
      weight: 3
    source: https://github.com/gardener/dashboard/blob/master/README.md

Adding Multiple Files

You can also add multiple topics to the website at once, either through linking a whole folder or a manifest than contains the documentation structure.

Linking a Folder

  - dir: <dir-name>
    structure:
    - fileTree: https://github.com/<path>/<folder>
Example
  - dir: development
    structure:
    - fileTree: https://github.com/gardener/gardener/tree/master/docs/development

Linking a Manifest File

- dir: <dir-name>
  structure:
  - manifest: https://github.com/<path>/manifest.yaml
Example
- dir: extensions
  structure:
  - manifest: https://github.com/gardener/documentation/blob/master/.docforge/documentation/gardener-extensions/gardener-extensions.yaml

Notes and Tips

  • If you want to place a file inside of an already existing directory in the main repo, you need to create a dir element that matches its name. If one already exists, simply add your link to its structure element.
  • You can chain multiple files, folders, and manifests inside of a single structure element.
  • For examples of frontmatter elements, see the Style Guide.

3 - Formatting Guide

This page gives writing formatting guidelines for the Gardener documentation. For style guidelines, see the Style Guide.

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

Type of TextFormattingMarkdown Syntax
API Objects and Technical ComponentscodeDeploy a `Pod`.
New Terms and EmphasisboldDo **not** stop it.
Technical NamescodeOpen file `root.yaml`.
User Interface ElementsitalicsChoose *CLUSTERS*.
Inline Code and Inline CommandscodeFor declarative management, use `kubectl apply`.
Object Field Names and Field ValuescodeSet the value of `image` to `nginx:1.8`.
Links and ReferenceslinkVisit the [Gardener website](https://gardener.cloud/)
Headersvarious# API Server

API Objects and Technical Components

When you refer to an API object, use the same uppercase and lowercase letters that are used in the actual object name, and use backticks (`) to format them. Typically, the names of API objects use camel case.

Don’t split the API object name into separate words. For example, use PodTemplateList, not Pod Template List.

Refer to API objects without saying “object,” unless omitting “object” leads to an awkward construction.

DoDon’t
The Pod has two containers.The pod has two containers.
The Deployment is responsible for…The Deployment object is responsible for…
A PodList is a list of Pods.A Pod List is a list of pods.
The gardener-control-manager has control loops…The gardener-control-manager has control loops…
The gardenlet starts up with a bootstrap kubeconfig having a bootstrap token that allows to create CertificateSigningRequest (CSR) resources.The gardenlet starts up with a bootstrap kubeconfig having a bootstrap token that allows to create CertificateSigningRequest (CSR) resources.

New Terms and Emphasis

Use bold to emphasize something or to introduce a new term.

DoDon’t
A cluster is a set of nodes …A “cluster” is a set of nodes …
The system does not delete your objects.The system does not(!) delete your objects.

Technical Names

Use backticks (`) for filenames, technical componentes, directories, and paths.

DoDon’t
Open file envars.yaml.Open the envars.yaml file.
Go to directory /docs/tutorials.Go to the /docs/tutorials directory.
Open file /_data/concepts.yaml.Open the /_data/concepts.yaml file.

User Interface Elements

When referring to UI elements, refrain from using verbs like “Click” or “Select with right mouse button”. This level of detail is hardly ever needed and also invalidates a procedure if other devices are used. For example, for a tablet you’d say “Tap on”.

Use italics when you refer to UI elements.

UI ElementStandard FormulationMarkdown Syntax
Button, Menu pathChoose UI Element.Choose *UI Element*.
Menu path, context menu, navigation pathChoose System > User Profile > Own Data.Choose *System* \> *User Profile* \> *Own Data*.
Entry fieldsEnter your password.Enter your password.
Checkbox, radio buttonSelect Filter.Select *Filter*.
Expandable screen elementsExpand User Settings.
Collapse User Settings.
Expand *User Settings*.
Collapse *User Settings*.

Inline Code and Inline Commands

Use backticks (`) for inline code.

DoDon’t
The kubectl run command creates a Deployment.The “kubectl run” command creates a Deployment.
For declarative management, use kubectl apply.For declarative management, use “kubectl apply”.

Object Field Names and Field Values

Use backticks (`) for field names, and field values.

DoDon’t
Set the value of the replicas field in the configuration file.Set the value of the “replicas” field in the configuration file.
The value of the exec field is an ExecAction object.The value of the “exec” field is an ExecAction object.
Set the value of imagePullPolicy to Always.Set the value of imagePullPolicy to “Always”.
Set the value of image to nginx:1.8.Set the value of image to nginx:1.8.
DoDon’t
Use a descriptor of the link’s destination: “For more information, visit Gardener’s website.”Use a generic placeholder: “For more information, go here.”
Use relative links when linking to content in the same repository: [Style Guide](../style-guide/_index.md)Use absolute links when linking to content in the same repository: [Style Guide](https://github.com/gardener/documentation/blob/master/website/documentation/contribute/documentation/style-guide/_index.md)

Another thing to keep in mind is that markdown links do not work in certain shortcodes (e.g., mermaid). To circumvent this problem, you can use HTML links.

Headers

  • Use H1 for the title of the topic. (# H1 Title)
  • Use H2 for each main section. (## H2 Title)
  • Use H3 for any sub-section in the main sections. (### H3 Title)
  • Avoid using H4-H6. Try moving the additional information to a new topic instead.

Code Snippet Formatting

Don’t Include the Command Prompt

DoDon’t
kubectl get pods$ kubectl get pods

Separate Commands from Output

Verify that the pod is running on your chosen node:
kubectl get pods --output=wide

The output is similar to:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents, for example:

Display information about a pod:

kubectl describe pod <pod-name>

<pod-name> is the name of one of your pods.

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.

4 - Markdown

Hugo uses Markdown 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.

However, use HTML judicially and to the minimum extent possible. Using HTML in markdowns makes it harder to maintain and publish coherent documentation bundles. This is a job typically performed by a publishing platform mechanisms, such as Hugo’s layouts. Considering that the source documentation might be published by multiple platforms you should be considerate in using markup that may bind it to a particular one.

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.

5 - Organization

The Gardener project implements the documentation-as-code paradigm. Essentially this means that:

  • Documentation resides close to the code it describes - in the corresponding GitHub repositories. Only documentation with regards to cross-cutting concerns that cannot be affiliated to a specific component repository is hosted in the general gardener/documentation repository.
  • We use tools to develop, validate and integrate documentation sources
  • The change management process is largely automated with automatic validation, integration and deployment using docforge and docs-toolbelt.
  • The documentation sources are intended for reuse and not bound to a specific publishing platform.
  • The physical organization in a repository is irrelevant for the tool support. What needs to be maintained is the intended result in a docforge documentation bundle manifest configuration, very much like virtual machines configurations, that docforge can reliably recreate in any case.
  • We use GitHub as distributed, versioning storage system and docforge to pull sources in their desired state to forge documentation bundles according to a desired specification provided as a manifest.

Content Organization

Documentation that can be affiliated to component is hosted and maintained in the component repository.

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
|_ docs
   |_ usage
   |  |_ images
   |  |_ 01.png
   |  |_ hibernation.md
   |_ operations
   |_ 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. While recommended, this is not a mandatory way of organizing the documentation.

  • User: usage
  • Operator: operations
  • Gardener (service) provider: deployment
  • Gardener Developer: development
  • Gardener Extension Developer: extensions

Publishing on gardener.cloud

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 and register a reference to your documentation.

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.

6 - Shortcodes

Shortcodes are the Hugo way to extend the limitations of Markdown before resorting to HTML. There are a number of built-in shortcodes available from Hugo. This list is extended with Gardener website shortcodes designed specifically for its content. Find a complete reference to the Hugo built-in shortcodes on its website.

Below is a reference to the shortcodes developed for the Gardener website.

alert

{{% alert color="info" title="Notice" %}}
text
{{% /alert %}}

produces

All the color options are info|warning|primary

You can also omit the title section from an alert, useful when creating notes.

It is important to note that the text that the “alerts” shortcode wraps will not be processed during site building. Do not use shortcodes in it.

You should also avoid mixing HTML and markdown formatting in shortcodes, since it won’t render correctly when the site is built.

Alert Examples

mermaid

The GitHub mermaid fenced code block syntax is used. You can find additional documentation at mermaid’s official website.

```mermaid
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
```

produces:

graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

Default settings can be overridden using the %%init%% header at the start of the diagram definition. See the mermaid theming documentation.

```mermaid
%%{init: {'theme': 'neutral', 'themeVariables': { 'mainBkg': '#eee'}}}%%
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
```

produces:

%%{init: {'theme': 'neutral', 'themeVariables': { 'mainBkg': '#eee'}}}%%
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

7 - Style Guide

This page gives writing style guidelines for the Gardener documentation. For formatting guidelines, see the Formatting Guide.

These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a Pull Request.

Structure

Documentation Types Overview

The following table summarizes the types of documentation and their mapping to the SAP UA taxonomy. Every topic you create will fall into one of these categories.

Gardener Content TypeDefinitionExampleContentComparable UA Content Type
ConceptIntroduce a functionality or concept; covers background information.ServicesOverview, Relevant headingsConcept
ReferenceProvide a reference, for example, list all command line options of gardenctl and what they are used for.Overview of kubectlRelevant headingsReference
TaskA step-by-step description that allows users to complete a specific task.Upgrading kubeadm clustersOverview, Prerequisites, Steps, ResultComplex Task
TrailCollection of all other content types to cover a big topic.Custom NetworkingNoneMaps
TutorialA combination of many tasks that allows users to complete an example task with the goal to learn the details of a given feature.Deploying Cassandra with a StatefulSetOverview, Prerequisites, Tasks, ResultTutorial

See the Contributors Guide for more details on how to produce and contribute documentation.

Topic Structure

When creating a topic, you will need to follow a certain structure. A topic generally comprises of, in order:

  • Metadata (Specific for .md files in Gardener) - Additional information about 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

  • 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.

Front Matter

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:

---
title: Getting Started
description: Guides to get you accustomed with Gardener
weight: 10
---

There are a number of 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.
  • description describes the content. For some content types such as documentation guides, it may be rendered in the UI.
  • weight a positive integer number that controls the ordering of the content in navigation structures.
  • 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!
  • persona specifies the type of user the topic is aimed towards. Use only a single persona per topic.
    persona: 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 documentation.

Images

If you want to add an image to your topic, it is recommended to follow the guidelines outlined in the Images 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

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 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

Creating Titles and Headers

  • Use title case 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

7.1 - Concept Topic Structure

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.

Relevant heading 1

This section gives the user all the information needed in order to understand the topic.

Relevant subheading

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.

7.2 - Reference Topic Structure

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.

Content TypeDefinitionExample
Name 1Definition of Name 1Relevant link
Name 2Definition of Name 2Relevant link

7.3 - Task Topic Structure

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.

Prerequisites

  • Prerequisite 1
  • Prerequisite 2

Steps

Avoid nesting headings directly on top of each other with no text inbetween.

  1. Describe step 1 here
  2. Describe step 2 here

Avoid nesting headings directly on top of each other with no text inbetween.

  1. Describe step 1 here
  2. Describe step 2 here

Result

Screenshot of the final status once all the steps have been completed.

Provide links to other relevant topics, if applicable. Once someone has completed these steps, what might they want to do next?