Concept Topic Structure
Describes the contents of a concept topic
그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그
4 minute read
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 Type | Definition | Example | Content | Comparable UA Content Type |
|---|---|---|---|---|
| Concept | Introduce a functionality or concept; covers background information. | Services | Overview, Relevant headings | Concept |
| Reference | Provide a reference, for example, list all command line options of gardenctl and what they are used for. | Overview of kubectl | Relevant headings | Reference |
| Task | A step-by-step description that allows users to complete a specific task. | Upgrading kubeadm clusters | Overview, Prerequisites, Steps, Result | Complex Task |
| Trail | Collection of all other content types to cover a big topic. | Custom Networking | None | Maps |
| Tutorial | A 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 StatefulSet | Overview, Prerequisites, Tasks, Result | Tutorial |
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
.mdfiles in Gardener) - Additional information about the topicTitle - 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 properites, but not all of them are considered by the layouts developed for the website. The most essential ones to consider are:
titlethe content title that will be used as page title and in navigation structures.descriptiondescribes the content. For some content types such as documentation guides, it may be rendered in the UI.weighta positive integer number that controls the ordering of the content in navigation structures.urlif 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!personaspecifies 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
Related Links
Reference Topic Structure
Describes the contents of a reference topic
Task Topic Structure
Describes the contents of a task topic