Skip to content
Open
Changes from all commits
Commits
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
10 changes: 9 additions & 1 deletion content/en/docs/contribute/style/page-content-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ The Kubernetes documentation follows several types of page content:
- Tutorial
- Reference

You may also find the [Diátaxis](https://diataxis.fr/) documentation framework
helpful as a reference for how to write each of these page content types.

<!-- body -->

## Content sections
Expand Down Expand Up @@ -137,9 +140,14 @@ Within each section, write your content. Use the following guidelines:
- Use a minimum of H2 headings (with two leading `#` characters). The sections
themselves are titled automatically by the template.
- For `overview`, use a paragraph to set context for the entire topic.
Briefly explain why a reader would want to perform this task (the motivation
or use case), so the reader can decide whether the page is relevant to them
before reading the steps.
- For `prerequisites`, use bullet lists when possible. Start adding additional
prerequisites below the `include`. The default prerequisites include a running Kubernetes cluster.
- For `steps`, use numbered lists.
- For `steps`, use numbered lists. Keep the focus on the task itself. If a
step requires substantial background, link to the relevant concept page
rather than repeating the explanation here.
- For discussion, use normal content to expand upon the information covered
in `steps`.
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
Expand Down