diff --git a/content/en/docs/contribute/style/page-content-types.md b/content/en/docs/contribute/style/page-content-types.md index 503183605ccdb..bc5a7ed397c4a 100644 --- a/content/en/docs/contribute/style/page-content-types.md +++ b/content/en/docs/contribute/style/page-content-types.md @@ -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. + ## Content sections @@ -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