Contributing Documentation

1 - Working with Images

Using images on the website has to contribute to the aesthetics and comprehensibility 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>

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

- file: _index.md
  frontmatter:
    title: <topic-name>
    description: <topic-description>
    weight: <weight>

Linking a Folder

  - dir: <dir-name>
    structure:
    - fileTree: https://github.com/<path>/<folder>

  - 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

- 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
• Code Snippet Formatting
• Related Links

Formatting of Inline Elements

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.

New Terms and Emphasis

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

Technical Names

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

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.

Inline Code and Inline Commands

Use backticks (`) for inline code.

Object Field Names and Field Values

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

Links and References

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

Separate Commands from Output

kubectl get pods --output=wide

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:

kubectl describe pod <pod-name>

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
• Contributors Guide

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 - Pull Request Description

Overview

When opening a pull request, it is best to give all the necessary details in order to help out the reviewers understand your changes and why you are proposing them. Here is the template that you will need to fill out:

**What this PR does / why we need it**:
<!-- Describe the purpose of this PR and what changes have been proposed in it -->
**Which issue(s) this PR fixes**:
Fixes #
<!-- If you are opening a PR in response to a specific issue, linking it will automatically 
close the issue once the PR has been merged -->
**Special notes for your reviewer**:
<!-- Any additional information your reviewer might need to know to better process your PR -->
**Release note**:
<!--  Write your release note:
1. Enter your release note in the below block.
2. If no release note is required, just write "NONE" within the block.

Format of block header: <category> <target_group>
Possible values:
- category:       improvement|noteworthy|action
- target_group:   user|operator|developer
-->
```other operator
EXAMPLE
\```

Writing Release Notes

Some guidelines and tips for writing release notes include:

• Be as descriptive as needed.
• Only use lists if you are describing multiple different additions.
• You can freely use markdown formatting, including links.

You can find various examples in the Releases sections of the gardener/documentation and gardener/gardener repositories.

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

8 - 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
  • Topic Structure
  • Front Matter
  • Alerts
  • Images
  • General Tips
• Language and Grammar
  • Language
  • Writing Style
  • Creating Titles and Headers
• Related Links

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.

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
  • Concept content: Overview, Relevant headings
  • Task content: Overview, Prerequisites, Steps, Result
  • Reference content: Relevant headings
• 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 properties, 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. The lower it is, the higher the topic will be on the page. Topics with no set weight are sorted in alphabetical order, with any weighted topics appearing above them.

• 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 succinct 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 succinct
• Task and tutorial topic titles begin with a verb

Related Links

• Formatting Guide
• Contributors Guide
• Shortcodes
• Images
• SAPterm

8.1 - Concept Topic Structure

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.

Related Links

• Link 1
• Link 2

8.2 - Reference Topic Structure

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.

Related Links

• Link 1
• Link 2

8.3 - Task Topic Structure

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

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
2. Describe step 2 here

Result

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