From 81db2cf1145111b9b0493e412f80907b0301d4a1 Mon Sep 17 00:00:00 2001 From: Tana M Berry Date: Thu, 3 Aug 2023 13:41:27 -0500 Subject: [PATCH] website/developer-docs: add new template for procedures (#6390) * new templete for procedural topics * edit sidebar * removed backslash * tweaks * template draft * fix sidebar Signed-off-by: Jens Langhammer --------- Signed-off-by: Jens Langhammer Co-authored-by: Tana Berry Co-authored-by: Jens Langhammer --- .../developer-docs/docs/templates/index.md | 15 ++++++++ .../docs/templates/procedural.md | 37 +++++++++++++++++++ website/sidebarsDev.js | 19 +++++++++- 3 files changed, 69 insertions(+), 2 deletions(-) create mode 100644 website/developer-docs/docs/templates/index.md create mode 100644 website/developer-docs/docs/templates/procedural.md diff --git a/website/developer-docs/docs/templates/index.md b/website/developer-docs/docs/templates/index.md new file mode 100644 index 000000000..7ae832890 --- /dev/null +++ b/website/developer-docs/docs/templates/index.md @@ -0,0 +1,15 @@ +--- +title: "Templates" +--- + +In technical docuemntation, there are document "types" (similar to how there are data types). + +The most common types are: + +- [**Procedural**](./procedural.md): these are How To docs, the HOW information, with step-by-step instructions for accomplishing a task. This is what most people are looking for when they open the docs... and best practice is to separate the procedural docs from long, lengthy conceptual or reference docs. + +- **Conceptual**: these docs provide the WHY information, and explain when to use a feature (or when not to!), and general concepts behind the fature or functioanlity. + +- **Reference**: this is typically tables or lists of reference information, such as configuration values, or most commmonly APIs. + +We have templates for the different types, to make it super-easy for whomever wants to contribute some documentation! diff --git a/website/developer-docs/docs/templates/procedural.md b/website/developer-docs/docs/templates/procedural.md new file mode 100644 index 000000000..a520022f4 --- /dev/null +++ b/website/developer-docs/docs/templates/procedural.md @@ -0,0 +1,37 @@ +--- +title: "Procedural topic" +--- + +Use a title that focuses on the task you are writing about... for example, "Add a new Group" or "Edit user profiles". For procedural docs, there should be a verb in the tilte, and usually the noun (the thing you are working on). For the title (and all headings) use the infinitive form of the verb (i.e. "add") not the gerund form (i.e. "adding"). + +In this first section write one or two sentences about the task. Keep it brief; if it goes on too long, then create a separate conceptual topic, in a separate `.md` file. We don't want readers to have to scroll through paragraphs of conceptual info before they get to Step 1. + +## Prerequisites (optional section) + +In this section, inform the reader of anything they need to do, or have configured or installed, before they start following the procedural instructions below. + +## Overview of steps/workflow (optional section) + +If the task is quite long or complex, it might be good to add a bullet list of the main steps, or even a diagram of the workflow, just so that the reader can first familairize themselves with the 50,000 meter view before they dive into the detailed steps. + +## first several group steps + +If the task involves a lot of steps, try to group them into simalr steps and have a Head3 or Hedad4 title for each group. + +In this section, help the reader get oriented... where do they need to be (i.e. in the GUI, on a CLI, etc). + +Have a separate paragraph for each step. + +Start instructions with the desired outcome, followed by the instructions. + +EXAMPLE: To define a new port number, navigate to the Admin interface, and then to the **Settings** tab. + +## next step of grouped steps + +Continue with the steps... + +Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. + +## verify the steps + +Whenever possible, it is useful to add verification steps at the end of a procedural topic. For example, if the procedural was about installing a product, use this section to tell them how they can verify that the install was successful diff --git a/website/sidebarsDev.js b/website/sidebarsDev.js index 5bf96540e..47361ce97 100644 --- a/website/sidebarsDev.js +++ b/website/sidebarsDev.js @@ -55,8 +55,23 @@ module.exports = { id: "translation", }, { - type: "doc", - id: "docs/writing-documentation", + type: "category", + label: "Writing documentation", + link: { + type: "doc", + id: "docs/writing-documentation", + }, + items: [ + { + type: "category", + label: "Templates", + link: { + type: "doc", + id: "docs/templates/index", + }, + items: ["docs/templates/procedural"], + }, + ], }, { type: "doc",