Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added relative link guideline & restructured Formatting Guide #401

Merged
merged 1 commit into from
Mar 17, 2023
Merged

Added relative link guideline & restructured Formatting Guide #401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Added relative link guideline + restructure
  • Loading branch information
@n-boshnakov
n-boshnakov committed Mar 15, 2023
commit b4229566d3d75653a80df3c80bd3e1bbe9a4fec8
85 changes: 41 additions & 44 deletions website/documentation/contribute/20_documentation/20_formatting_guide/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,30 +14,35 @@ These are guidelines, not rules. Use your best judgment, and feel free to propos

| Type of Text | Formatting | Markdown Syntax |
|:---|:---|:---|
| [User Interface Elements](#user-interface-elements) | *italics* | `Choose *CLUSTERS*`. |
| [API Objects and Technical Components](#api-objects-and-technical-components) | `code` | <code>Deploy a \`Pod\`.</code> |
| [New Terms and Emphasis](#new-terms-and-emphasis) | **bold** | `Do **not** stop it.` |
| [Technical Names](#technical-names) | `code` | <code>Open file \`root.yaml\`.</code> |
| [API Objects and Technical Components](#api-objects-and-technical-components) | `code` | <code>Deploy a \`Pod\`.</code> |
| [User Interface Elements](#user-interface-elements) | *italics* | `Choose *CLUSTERS*`. |
| [Inline Code and Inline Commands](#inline-code-and-inline-commands)| `code` | <code>For declarative management, use \`kubectl apply\`.</code> |
| [Object Field Names and Field Values](#object-field-names-and-field-values)|`code` | <code>Set the value of \`image\` to \`nginx:1.8\`.</code> |
| [Links and References](#links-and-references) | [link]() | `Visit the [Gardener website](https://gardener.cloud/)` |
| [Headers](#headers) | various | `# API Server`
| [Headers](#headers) | various | `# API Server` |


### User Interface Elements
### API Objects and Technical Components

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".
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](https://en.wikipedia.org/wiki/Camel_case).

Use *italics* when you refer to UI elements.
Don't split the API object name into separate words. For example, use
`PodTemplateList`, not Pod Template List.

| UI Element | Standard Formulation | Markdown Syntax |
|:---|:---|:---|
| Button, Menu path | Choose *UI Element*. | `Choose *UI Element*.` |
| Menu path, context menu, navigation path | Choose *System* \> *User Profile* \> *Own Data*. | `Choose *System* \> *User Profile* \> *Own Data*.` |
| Entry fields | Enter your password. | `Enter your password.` |
| Checkbox, radio button | Select *Filter*. | `Select *Filter*.` |
| Expandable screen elements | Expand *User Settings*.<br>Collapse *User Settings*. | `Expand *User Settings*`.<br>`Collapse *User Settings*.` |
Refer to API objects without saying "object," unless omitting "object"
leads to an awkward construction.

| Do | Don'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

Expand All @@ -48,38 +53,29 @@ Use **bold** to emphasize something or to introduce a new term.
| 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 code style (using backticks) for filenames, technical componentes, directories, and paths.
Use backticks (\`) for filenames, technical componentes, directories, and paths.

| Do | Don'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

### 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](https://en.wikipedia.org/wiki/Camel_case).

Don't split the API object name into separate words. For example, use
`PodTemplateList`, not Pod Template List.
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".

Refer to API objects without saying "object," unless omitting "object"
leads to an awkward construction.
Use *italics* when you refer to UI elements.

| Do | Don'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. |
| UI Element | Standard Formulation | Markdown Syntax |
|:---|:---|:---|
| Button, Menu path | Choose *UI Element*. | `Choose *UI Element*.` |
| Menu path, context menu, navigation path | Choose *System* \> *User Profile* \> *Own Data*. | `Choose *System* \> *User Profile* \> *Own Data*.` |
| Entry fields | Enter your password. | `Enter your password.` |
| Checkbox, radio button | Select *Filter*. | `Select *Filter*.` |
| Expandable screen elements | Expand *User Settings*.<br>Collapse *User Settings*. | `Expand *User Settings*`.<br>`Collapse *User Settings*.` |

### Inline Code and Inline Commands

Expand All @@ -96,24 +92,25 @@ Use backticks (\`) for field names, and field values.

| Do | Don'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 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`. | the value of `image` to nginx:1.8. |
| Set the value of `image` to `nginx:1.8`. | Set the value of `image` to nginx:1.8. |

### Links and References

| Do | Don'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 a descriptor of the link's destination: "For more information, visit [Gardener's website](#links-and-references)." | Use a generic placeholder: "For more information, go [here](#links-and-references)." |
| Use relative links when linking to content in the same repository: `[Style Guide](../40_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/20_documentation/40_style_guide/_index.md)` |

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

### Headers

* Use H1 for the title of the topic.
* Use H2 for each main section.
* Use H3 for any sub-section in the main sections.
* 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
Expand Down Expand Up @@ -154,10 +151,10 @@ kubectl describe pod <pod-name>

</code>

### Versioning Kubernetes examples
### 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
## Related Links
* [Style Guide](../40_style_guide/_index.md)
* [Contributors Guide](../_index.md)
* [Contributors Guide](../../_index.md)
4 changes: 2 additions & 2 deletions website/documentation/contribute/20_documentation/40_style_guide/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,9 +106,9 @@ If you want to add an image to your topic, it is recommended to follow the guide
* Concept and reference topic titles should be simple and succint
* Task and tutorial topic titles begin with a verb

## Related links
## Related Links
* [Formatting Guide](../20_formatting_guide/_index.md)
* [Contributors Guide](../_index.md)
* [Contributors Guide](../../_index.md)
* [Shortcodes](../30_shortcodes/_index.md)
* [Images](../45_images/_index.md)
* [SAPterm](https://www.sapterm.com/)