Quickstart template and example

manual/1-design-the-information/document-types/quickstart-help-me-get-started.md

@@ -85,7 +85,7 @@ This information-type [admonition](../../20-style-the-content/12-admonitions.md)
 Guidelines:
 
 - Use the "Overview" H2 heading for this section.
-- Start with a brief discussion of this product or feature and its core purposes. Then describe what the user can accomplish in this quickstart.
+- Start with what the user can accomplish in this quickstart. Then add a brief discussion of this product or feature and its core purposes.
 - The overview should be one or a maximum of two paragraphs. Use an additional [concept](./concept-help-me-to-understand.md) article if you need to provide more information.
 - Link to related topics to support the reader's gathering of information.
 

manual/2-populate-the-structure/canonical-examples/quickstart-example.md

@@ -0,0 +1,99 @@
+---
+title: Quickstart
+topic: Repositories
+author: jorge-campo, cheny0
+version: 1
+url: docs/repositories/quickstart
+---
+
+<!-- This document is an example for the concept template. It is not a real document and should be used for illustration purposes only. -->
+
+# Quickstart
+
+#### Create and manage your first repository quickly.
+
+> 📒 **Note**  
+> You can create repositories in your personal account or any organization where you have the required permissions.
+
+## Overview
+
+In this quickstart, you create a repository, edit a file, and clone the repository to your computer. This helps you begin collaborating or versioning your code immediately.
+
+Repositories are project containers on GitHub. They store source code, configuration, and related files.
+
+## Before you start
+
+Before you begin, make sure you have:
+
+- A GitHub personal or organization [account](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts)
+- [Git command line tool](https://git-scm.com/)
+
+## Create a repository
+
+1. In the upper-right corner of any GitHub page, click **+** and choose **New repository**.  
+    ![An image showing the new repository option](./quickstart-example/create-a-repository-step-1.png)
+2. Enter a repository name.  
+3. Optionally, add a description.  
+4. For **Choose visibility**, select **Public** or **Private**.
+5. Click the toggle to include add a README.
+6. Click **Create repository**.   
+
+## Commit a change to the README
+
+A [commit](https://docs.github.com/en/get-started/learning-about-github/github-glossary#commit) is like a snapshot of all the files in your project at a particular point in time. Committing a change means to save your changes to the repository.
+
+### Edit the README
+
+1. In the upper-right corner of any GitHub page, click your profile picture, and then click **Your repositories**.
+2. Click your repository name.
+3. In your repository's list of files, select `README.md`.
+    ![An image showing the README.md file in the file list](./quickstart-example/edit-the-readme-step-3.png)
+4. In the upper right corner of the file view, click ![Edit icon](./quickstart-example/edit-icon.png) to open the file editor.
+5. In the text box, type some information about your project.
+6. Above the new content, click **Preview**.
+7. Review the changes you made to the file. If you select **Show diff**, you will see the new content in green.
+
+### Commit the change
+
+1. Click **Commit changes...**
+2. In the **Commit message** field, type a short, meaningful commit message that describes the change you made to the file.
+3. Select **Commit directly to the main branch**.
+4. Click **Commit changes**.
+
+## Clone the repository locally
+
+Cloning a repository from GitHub.com to your local computer makes it easier to fix merge conflicts, add or remove files, and push larger commits.
+
+### Copy the URL
+
+1. In the upper-right corner of any GitHub page, click your profile picture, and then click **Your repositories**.
+2. Click your repository name.
+3. Above the list of files, click **<> Code**.
+4. Under **HTTPS**, click ![Copy icon](./quickstart-example/copy-icon.png).
+
+### Clone the repository
+
+1. Open a terminal on your computer.
+2. Run `cd /path/to/your/directory` to change the current working directory to the location where you want the cloned directory.
+3. Type `git clone`, and then paste the URL you copied earlier.
+
+    ```shell
+    git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
+    ```
+
+4. Press **Enter** to create your local clone.
+
+    ```text
+    $ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
+    Cloning into 'Spoon-Knife'...
+    remote: Counting objects: 10, done.
+    remote: Compressing objects: 100% (8/8), done.
+    remote: Total 10 (delta 1), reused 10 (delta 1)
+    Unpacking objects: 100% (10/10), done.
+    ```
+
+## Next steps
+
+- [Create a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)
+- [Manage user access to your organization's repositories](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories)
+- [Add a security policy to your repository](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)

manual/2-populate-the-structure/templates/template-quickstart.md

@@ -0,0 +1,206 @@
+| Section                       | Format                 | Required | ID                    |
+|:------------------------------|:-----------------------|:---------|:----------------------|
+| Title                         | H1                     | Yes      | `QST-PAGE-TITLE`      |
+| Subtitle                      | Single bold sentence   | Yes      | `QST-PAGE-SUBTITLE`   |
+| Access callout                | Information admonition | Note-type callout | `QST-ACCESS` |
+| Callouts                      | Tip, Note, Important, Caution | No  | `QST-CALLOUTS`        |
+| Overview                      | Paragraph              | Yes      | `QST-OVERVIEW`        |
+| "Before you start" title      | H2                     | No       | `QST-BEFORE-START-001` |
+| "Before you start" list       | Bullet list            | No       | `group: QST-BEFORE-START` |
+| Task titles                   | H2                     | Yes      | `group: QST-TASK-TITLE` |
+| Task steps                    | Numbered list          | Yes      | `group: QST-TASK`     |
+| "Next steps" title            | H2                     | No       | `QST-NEXT-001`        |
+| "Next steps" list             | Bullet list            | No       | `group: QST-NEXT`     |
+| Article length                | ~1,200 words           | -        | `QST-EXTRA-001`       |
+| H4-H6 headings                | -                      | Forbidden| `QST-EXTRA-002`       |
+
+## Front matter
+---
+title:
+doc_type: # [procedure, concept, reference, quickstart, api]
+product: # [codex, nomos, waku]
+topics: []
+steps_layout: # [flat|sectioned]
+authors: # GitHub username
+owner: ift
+doc_version: # increased by one after every update
+slug:
+---
+
+## Title (H1) guidelines <!-- group: QST-PAGE-TITLE -->
+
+- Use a Markdown H1 heading. <!-- QST-PAGE-TITLE-001 -->
+- Use only the word "Quickstart" as the title. <!-- QST-PAGE-TITLE-002 -->
+
+## Subtitle guidelines <!-- group: QST-PAGE-SUBTITLE -->
+
+- Single sentence with no links, list items, or formatting. Ends with a period. <!-- QST-PAGE-SUBTITLE-001 -->
+- Use bold format. Stay under 120 characters. <!-- QST-PAGE-SUBTITLE-002 -->
+- Use imperative verbs to describe the topic's purpose or benefit: *Explore*, *Get started*, *Try*, and so on. <!-- QST-PAGE-SUBTITLE-003 -->
+- Adds new value beyond the title. It should not repeat the title or be a rephrased version of it. <!-- QST-PAGE-SUBTITLE-004 -->
+
+**Examples:**
+
+- *Get hands-on with Waku’s key capabilities.*
+- *Quickly add payments to your project with Stripe.*
+
+## Access callout guidelines <!-- group: QST-ACCESS -->
+
+This note-type callout is exclusively to alert readers about what roles, permissions, or product versions are required to perform the procedure.
+
+- Place it after the title and subtitle, before the overview. <!-- QST-ACCESS-001 -->
+- Use the `Note` callout style. <!-- QST-ACCESS-002 -->
+- Start with the phrase: *This feature is available to users with...* or *To perform this procedure, you need...* <!-- QST-ACCESS-003 -->
+- Focus on required roles, permissions, or product versions only. Don't include any other prerequisite such as knowledge, skills, or tools. <!-- QST-ACCESS-004 -->
+
+**Examples:**
+
+- *This feature is available to admin roles in version 5.0 or later with write permissions on the repository.*
+- *This procedure requires contributor roles in version 2.3 or higher and read/write access to the API endpoints.*
+
+## Callouts guidelines <!-- QST-CALLOUTS -->
+
+- Use callouts sparingly in the document and only when necessary to avoid overwhelming the reader. <!-- QST-CALLOUTS-001 -->
+- One callout maximum per section <!-- QST-CALLOUTS-002 -->
+- Keep them concise. <!-- QST-CALLOUTS-003 -->
+- Use the appropriate type: `Tip`, `Note`, `Important`, or `Caution`. <!-- QST-CALLOUTS-004 -->
+
+## Overview guidelines <!-- group: QST-OVERVIEW -->
+
+- Describe the product or feature' core purposes and what the user will achieve in this quickstart. <!-- QST-OVERVIEW-001 -->
+- Write one or two 50 to 100-word paragraphs. Use an additional [concept](./concept-help-me-to-understand.md) article if you need to provide more information. <!-- QST-OVERVIEW-002 -->
+- Link to related documents or headings in the same document to support the reader's gathering of information. <!-- QST-OVERVIEW-003 -->
+
+## "Before you start" (optional) guidelines <!-- group: QST-BEFORE-START -->
+
+- Use the "Before you start" H2 heading for this section. <!-- QST-BEFORE-START-001 -->
+- Provide a bullet list describing: <!-- QST-BEFORE-START-002 -->
+    - The intended audience of this quickstart.
+    - Required prior knowledge for using this quickstart.
+    - The software or hardware requirements.
+- Use noun phrases. Don't include verbs such as "learn" or "prepare". <!-- QST-BEFORE-START-003 -->
+- Provide [links](../../20-style-the-content/10-links.md) to related content such as installation instructions or articles that provide required knowledge. <!-- QST-BEFORE-START-004 -->
+- Don't include the procedure for setting up or installing prerequisites. If you must explain the procedure and it takes less than three steps, include it in the [task](#task-section) where you describe setting up your product. <!-- QST-BEFORE-START-005 -->
+
+> ⚙️ **Example:**
+>
+> Before you begin, make sure you have:
+>
+> - A basic understanding of [Ethereum](https://ethereum.org/en/developers/docs/intro-to-ethereum/) ↗ concepts
+> - Proficiency with the command line
+> - A machine running Ubuntu Linux with the following minimum requirements:
+>   - 4 GB memory
+>   - 2 TB SSD
+>   - Linux 64-bit
+
+## Task guidelines: <!-- group: QST-TASK -->
+
+- Choose two or three tasks that are essential, quick to complete, and provide immediate value to the user. <!-- QST-TASK-001 -->
+    - The first task is usually about setting up or installing the product or feature. However, if setup requires more than seven steps, create a separate installation guide and direct readers to it in the [Before you start](#before-you-start-section) section. <!-- QST-TASK-002 -->
+    - For the other task(s), focus on the core functionalities of the product or feature. <!-- QST-TASK-003 -->
+
+### Task procedural structure 
+
+- Tasks in a quickstart always use the `sectioned` procedural structure. <!-- QST-TASK-004 -->
+- Don't use subtasks. Split into additional H2 task groups or use the sectioned layout instead. <!-- QST-TASK-005 -->
+
+> **Note**
+>
+> See [Steps structure: flat vs. sectioned](./procedure.md#steps-structure-flat-vs-sectioned) for guidance.
+
+### Task layout
+
+| Element (per task) | Format                          | Required | ID                      | Rules           |
+| :----------------- | :------------------------------ | :------: | :---------------------- | :---------------|
+| Task title         | H2                              |    Yes   | `QST-TASK-TITLE` | PROC-TASK-TITLE |
+| Task intro         | Paragraph                       |    No    | `QST-TASK-INTRO` | PROC-INTRO      |
+| Task callout       | Callout                         |    No    | `QST-TASK-CALL`  | PROC-CALL       |
+| Task actions       | Numbered list                   |    Yes   | `QST-TASK-STEPS` | PROC-STEP       |
+| Clarifiers         | Unordered bullets (depth 1) (2) |    No    | `QST-TASK-BUL`   | PROC-BUL        |、
+
+| Code               | Fenced code block               |    No    | `QST-TASK-CODE`  | PROC-CODE       |
+| Screenshot         | Image                           |    No    | `QST-TASK-IMG`   | PROC-SHOT       |
+
+(1) Use a short bullet list for clarifiers or alternatives. Do not create numbered sub-steps.
+
+> **Note:**
+>
+> The `Rules` column points to the shared rule group that governs this element (see [Procedure guidelines](#procedure-guidelines)).
+
+### Task title (H2) guidelines <!-- group: QST-TASK-TITLE -->
+
+- Task titles are Markdown H2 headings. <!-- QST-TASK-TITLE-LEVEL-H2 -->
+- Don’t include numbering in the title. <!-- QST-TASK-HEADING -->
+- Aim for 50–60 characters; 80 max. <!-- QST-TASK-TITLE-LEN -->
+- Start with an imperative verb; avoid the *-ing* form. <!-- QST-TASK-TITLE-VOICE -->
+- Use sentence case (capitalize only the first word and proper nouns). <!-- QST-TASK-TITLE-CASE -->
+- Avoid empty verbs (*make*, *manage*, *put*). <!-- QST-TASK-TITLE-VERB-SPECIFIC -->
+- Avoid one- or two-word titles. <!-- QST-TASK-TITLE-NO-2WORD -->
+- Don’t use punctuation marks in titles (colons, semicolons, dashes). <!-- QST-TASK-TITLE-NO-PUNCT -->
+
+> ⚙️ **Example:**
+>
+> - *Run a Waku node*
+> - *Connect to the Codex network*
+> - *Configure system admin access*
+
+### Task introduction (optional) guidelines <!-- group: QST-TASK-INTRO -->
+
+- Write 1–2 short sentences that provide context. <!-- QST-TASK-INTRO-BRIEF -->
+- Do not repeat the task title wording. <!-- QST-TASK-INTRO-NO-REPEAT -->
+- Add cross-references here, not inside steps. <!-- QST-TASK-INTRO-LINKS -->
+
+### Task callout (optional) guidelines <!-- group: QST-TASK-CALL -->
+
+- Use one callout after the intro for important notes, warnings, or tips. <!-- QST-TASK-CALL-ONCE -->
+- Do not place callouts between steps. <!-- QST-TASK-CALL-NO-BETWEEN -->
+- One callout maximum per task. <!-- QST-TASK-CALL-ONE -->
+
+### Task steps guidelines:
+
+- Use a numbered list. <!-- QST-TASK-STEP-LIST-ORDERED -->
+- Start each step with an imperative verb; avoid *-ing* forms. <!-- QST-TASK-STEP-VERB -->
+- One step = one user action (combine only trivial actions). <!-- QST-TASK-STEP-ONE-ACTION -->
+- All steps must use number `1` (1, 1, 1, ... instead of 1, 2, 3, ...) <!-- QST-TASK-STEP-ALL-ONE -->
+- Aim for 2–7 steps. Split if longer. <!-- QST-TASK-STEP-RANGE -->
+- Avoid one-step tasks. <!-- QST-TASK-STEP-NO-ONE -->
+- When adding paragraphs, images, or code under a step, insert a blank line and indent to align with the first text after the list marker. <!-- QST-TASK-STEP-BLOCKS -->
+- Bold UI elements (buttons, menus, options). <!-- QST-TASK-STEP-UI-BOLD -->
+- Use inline code for commands, filenames, paths, and output. <!-- QST-TASK-STEP-CODE-INLINE -->
+- Don’t use external links in steps; only same-page anchors. <!-- QST-TASK-STEP-LINKS-INTERNAL -->
+- For UI paths, put location before action. <!-- QST-TASK-STEP-LOC-FIRST -->
+- For conditions, write the result first, then the condition. <!-- QST-TASK-STEP-RESULT-FIRST -->
+
+### Clarifiers (optional) guidelines <!-- group: QST-TASK-BUL -->
+
+- Don't use numbered substeps beneath a step (nested ordered lists). <!-- QST-TASK-BUL-NOSUBTASK -->
+- Use bullets for subactions, such as clarifiers or alternatives. <!-- QST-TASK-BUL-BULLETS -->
+- Limit clarifiers to 2–4 items in one level. <!-- QST-TASK-BUL-LIMIT -->
+
+### Task code (optional) guidelines <!-- group: QST-TASK-CODE -->
+
+Follow the code rules in the Style Guide. <!-- QST-TASK-CODE-LINK -->
+
+**Example:**
+
+    1. Do this thing...
+
+    ```bash
+    gh workflow run build --repo org/repo
+    ```
+
+### Task screenshot (optional) guidelines <!-- group: QST-TASK-SHOT -->
+
+Follow the Screenshots rules in the Style Guide. <!-- QST-TASK-SHOT-LINK -->
+
+## `Next steps` (optional) guidelines <!-- group: QST-NEXT -->
+
+- Use the "Next steps" H2 heading for this section. <!-- QST-NEXT-001 -->
+- Write a bullet list of links to articles about other tasks that the users can try after completing the quickstart. <!-- QST-NEXT-002 -->
+- Write at most three articles. <!-- QST-NEXT-003 -->
+- Consider a logical connection from the current quickstart that can act as a basis for users' next learning. <!-- QST-NEXT-004 -->
+
+## Extra content guidelines <!-- group: QST-EXTRA -->
+
+- The entire quickstart should be about 1 200 words long. <!-- QST-EXTRA-001 -->
+- Do not use H4-H6 headings. <!-- QST-EXTRA-002 -->