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,97 @@
+---
+title: Quickstart for GitHub Repositories
+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 for GitHub Repositories
+
+#### 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.
+
+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/quickstart/quickstart-template.md

@@ -0,0 +1,191 @@
+| Section                       | Format                              | Required  | ID                               |
+|:------------------------------|:------------------------------------|:----------|:---------------------------------|
+| Title                         | H1                                  | Yes       | `QST-TITLE`                      |
+| Subtitle                      | Single bold sentence                | Yes       | `QST-SUBTITLE`                   |
+| Access callout                | Note-type callout                   | No        | `QST-ACCESS`                     |
+| Callouts                      | Tip, Note, Important, Caution       | No        | `QST-CALLOUTS`                   |
+| Overview                      | Paragraph                           | Yes       | `QST-OVERVIEW`                   |
+| "Before you start" title      | H2                                  | No        | `QST-STRUCT-BEFORE-START-H2-TEXT`|
+| "Before you start" list       | Bullet list                         | No        | `QST-BEFORE-START`               |
+| Task title                    | H2                                  | Yes       | `QST-TASK-TITLE`                 |
+| Task intro                    | Paragraph                           | No        | `QST-TASK-INTRO`                 |
+| Task callout                  | Callout                             | No        | `QST-TASK-CALLOUTS`              |
+| Task actions                  | Numbered list                       | Yes       | `QST-TASK-STEP`                  |
+| Clarifiers                    | Unordered bullets (depth 1) (2)     | No        | `QST-TASK-CLARIFIERS`            |
+| Code                          | Fenced code block                   | No        | `QST-TASK-CODE`                  |
+| Screenshot                    | Image                               | No        | `QST-TASK-IMG`                   |
+| H4-H6 headings                | -                                   | Forbidden | `QST-STRUCT-FORBID-H4-H6`        |
+| "Next steps" title            | H2                                  | No        | `QST-STRUCT-NEXT-H2-TEXT`        |
+| "Next steps" list             | Bullet list                         | No        | `QST-NEXT`                       |
+
+## Front matter
+---
+title:
+doc_type: # [procedure, concept, reference, quickstart, api]
+product: # [storage, blockchain, communication]
+topics: []
+authors: # GitHub username
+owner: ift
+doc_version: # increased by one after every update
+slug:
+---
+
+## Title <!-- group: QST-TITLE -->
+
+- Use a Markdown H1 heading. <!-- QST-STRUCT-TITLE-H1 -->
+- The title consists of the phrase "Quickstart for" and the name of the project or feature. Do not add other text. For example, "Quickstart for Logos Storage". <!-- QST-BEHAV-TITLE-IMPERATIVE  -->
+
+## Subtitle <!-- group: QST-SUBTITLE -->
+
+- Use a Markdown H4 for the subtitle placed right under the H1. <!-- QST-STRUCT-SUBTITLE-H4 -->
+- Single sentence with no links, list items, or formatting. Ends with a period. <!-- -BEHAV-SUBTITLE-SINGLE-SENTENCE -->
+- Do not end with a period. <!-- QST-BEHAV-SUBTITLE-NO-PERIOD -->
+- Stay under 120 characters (approx. 20 words). <!-- QST-BEHAV-SUBTITLE-LENGTH-120 -->
+- Use imperative verbs to describe the topic's purpose or benefit: *Explore*, *Get started*, *Try*, and so on. <!-- QST-BEHAV-SUBTITLE-IMPERATIVE -->
+- Adds new value beyond the title. It should not repeat the title or be a rephrased version of it. <!-- QST-BEHAV-SUBTITLE-ADDS-VALUE -->
+
+**Examples:**
+
+- *Get hands-on with Waku's key capabilities.*
+- *Quickly add payments to your project with Stripe.*
+
+## Access callout <!-- 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-STRUCT-ACCESS-AFTER-SUBTITLE -->
+- Use the `Note` callout style. <!-- QST-STRUCT-ACCESS-NOTE-STYLE -->
+- Use label-led, scannable content (no explanations). <!-- QST-BEHAV-ACCESS-LABELED -->
+- Include permissions (software role or permission level). <!-- QST-BEHAV-ACCESS-PERMISSIONS -->
+- Include product (product version or edition), if applicable. <!-- QST-BEHAV-ACCESS-PRODUCT -->
+- If multiple permissions/products apply, use commas. <!-- QST-BEHAV-ACCESS-LIST-IF-MANY -->
+- Do not include knowledge, skills, or required tools. <!-- QST-BEHAV-ACCESS-SCOPE-ONLY -->
+- Omit the callout entirely if no permission/product constraints exist. <!-- QST-STRUCT-ACCESS-OMIT-IF-EMPTY -->
+
+**Examples:**
+
+  > **Note**
+  >
+  > - **Permissions**: Admin roles with write permissions on the repository 
+  > - **Product**: version 5.0 or later 
+
+## Callouts <!-- QST-CALLOUTS -->
+
+- Use callouts sparingly in the document and only when necessary to avoid overwhelming the reader. <!-- QST-STRUCT-CALLOUTS-NOT-CONSECUTIVE -->
+- One callout maximum per section <!-- QST-STRUCT-CALLOUTS-PER-SECTION-ONE -->
+- Keep each callout concise (≤ 2 short sentences). If the content needs a list or multiple paragraphs, move it into the body under a heading. <!-- QST-BEHAV-CALLOUTS-CONCISE -->
+- Ensure the callout content is directly relevant to the nearby task or decision point. <!-- QST-BEHAV-CALLOUTS-RELEVANT -->
+- Use the appropriate type: `Tip`, `Note`, `Important`, or `Caution`. <!-- QST-BEHAVE-CALLOUTS-TYPE -->
+- Do **not** include full procedural steps or long prerequisite checklists inside callouts. Put steps in the main flow; keep prerequisite lists in "Before you start." <!-- PROC-BEHAV-CALLOUTS-NO-STEPS -->
+- For the allowed callout types and when to use them, see the [writing rules](../../3-validating-design/writing-rules/README.md). <!-- PROC-BEHAV-CALLOUTS-TYPES-REFER-STYLEGUIDE -->
+
+## Overview <!-- group: QST-OVERVIEW -->
+
+- Describe the product or feature' core purposes and what the user will achieve in this quickstart. <!-- QST-BEHAV-OVERVIEW-CONTENT -->
+- Write one or two 50 to 100-word paragraphs. <!-- QST-BEHAV-OVERVIEW-LENGTH -->
+- Avoid lengthy discussions of the product or feature. Link to a [concept](./concept-help-me-to-understand.md) article if you need to provide more information. <!-- QST-BEHAV-OVERVIEW-MORE-INFO -->
+- Link to related documents or headings in the same document to support the reader's gathering of information. <!-- QST-BEHAV-OVERVIEW-LINK -->
+
+## "Before you start" (optional) <!-- group: QST-BEFORE-START -->
+
+- Use the "Before you start" H2 heading for this section. <!-- QST-STRUCT-BEFORE-START-H2-TEXT -->
+- Write a single unordered list. <!-- QST-STRUCT-BEFORE-UNORDERED -->
+- Specify the intended audience of this quickstart, required prior knowledge for using this quickstart and the software or hardware requirements. <!-- QST-BEHAV-BEFORE-CONTENT -->
+- Use noun phrases (For example, "familiarity with Golang"). Don't include verbs such as "learn" or "prepare". <!-- QST-BEHAV-BEFORE-START-NOUN -->
+- Provide [links](../../20-style-the-content/10-links.md) to related content such as installation instructions or articles that provide required knowledge. <!-- QST-BEHAV-BEFORE-START-LINK -->
+- Don't include the procedure for setting up or installing prerequisites. If you must explain the procedure, link to the corresponding document or resource. <!-- QST-BEHAV-BEFORE-START-NO-STEPS -->
+
+> ⚙️ **Example:**
+>
+> Before you begin, make sure you have:
+>
+> - A basic understanding of [Ethereum](https://ethereum.org/en/developers/docs/intro-to-ethereum/) ↗ concepts
+> - Knowledge of how to work with Python virtual environments
+> - 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-STRUCT-TASK-COUNT -->
+    - 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-BEHAV-TASK-SETUP -->
+    - For the other task(s), focus on the core functionalities of the product or feature. <!-- QST-BEHAV-TASK-CORE-FEATURES -->
+
+### Task title <!-- group: QST-TASK-TITLE -->
+
+- Task titles are Markdown H2 headings. <!-- QST-STRUCT-TASK-TITLE-H2 -->
+- Don't include numbering in the title. <!-- QST-BEHAV-TASK-TITLE-NO-NUMBERING -->
+- Aim for 50–60 characters; 80 max. <!-- QST-BEHAV-TASK-TITLE-LENGTH -->
+- Start with an imperative verb; avoid the *-ing* form. <!-- QST-BEHAV-TASK-TITLE-IMPERATIVE -->
+- Use sentence case (capitalize only the first word and proper nouns). <!-- QST-BEHAV-TASK-TITLE-SENTENCE-CASE -->
+- Avoid empty verbs (*make*, *manage*, *put*). <!-- QST-BEHAV-TASK-TITLE-NO-EMPTY-VERBS -->
+- Avoid one- or two-word titles. <!-- QST-BEHAV-TASK-TITLE-NO-ONE-TWO-WORD -->
+- Don't use punctuation marks in titles (colons, semicolons, dashes). <!-- QST-BEHAV-TASK-TITLE-NO-PUNCT -->
+B
+> ⚙️ **Example:**
+>
+> - *Run a Waku node*
+> - *Connect to the Codex network*
+> - *Configure system admin access*
+
+### Task introduction (optional) <!-- group: QST-TASK-INTRO -->
+
+- Write 1–2 short sentences that provide context. <!-- QST-BEHAV-TASK-INTRO-BRIEF -->
+- Do not repeat the task title wording. <!-- QST-BEHAV-TASK-INTRO-NO-REPEAT -->
+- Add cross-references here, not inside steps. <!-- QST-BEHAV-TASK-INTRO-LINKS -->
+
+### Task callout (optional) <!-- group: QST-TASK-CALLOUTS -->
+
+- Use one callout after the intro for important notes, warnings, or tips. <!-- QST-STRUCT-TASK-CALLOUTS-AFTER-INTRO -->
+- Do not place callouts between steps. <!-- QST-STRUCT-TASK-CALLOUTS-NO-BETWEEN-STEPS -->
+- One callout maximum per task. <!-- QST-STRUCT-TASK-CALLOUTS-PER-TASK-ONE -->
+
+### Task steps <!-- group: QST-TASK-STEP -->
+
+- Use a numbered list. <!-- QST-BEHAV-TASK-STEP-ORDERED -->
+- Start each step with an imperative verb; avoid *-ing* forms. <!-- QST-BEHAV-TASK-STEP-VERB -->
+- One step = one user action (combine only trivial actions). <!-- QST-BEHAV-TASK-STEP-ONE-ACTION -->
+- All steps must use number `1` (1, 1, 1, ... instead of 1, 2, 3, ...) <!-- QST-BEHAV-TASK-STEP-ALL-ONE -->
+- Aim for 2–7 steps. Split if longer. <!-- QST-BEHAV-TASK-STEP-RANGE -->
+- Avoid one-step tasks. <!-- QST-BEHAV-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-BEHAV-TASK-STEP-BLOCKS -->
+- Bold UI elements (buttons, menus, options). <!-- QST-BEHAV-TASK-STEP-UI-BOLD -->
+- Use inline code for commands, filenames, paths, and output. <!-- QST-BEHAV-TASK-STEP-CODE-INLINE -->
+- Don't use external links in steps; only same-page anchors. <!-- QST-BEHAV-TASK-STEP-LINKS -->
+- For UI paths, put location before action. <!-- QST-BEHAV-TASK-STEP-LOC-FIRST -->
+- For conditions, write the result first, then the condition. <!-- QST-BEHAV-TASK-STEP-RESULT-FIRST -->
+
+### Clarifiers (optional) <!-- group: QST-TASK-CLARIFIERS -->
+
+- Don't use numbered substeps beneath a step (nested ordered lists). <!-- QST-STRUCT-TASK-CLARIFIERS-NOSUBSTEPS -->
+- Use bullets for subactions, such as clarifiers or alternatives. <!-- QST-STRUCT-TASK-CLARIFIERS-BULLETS -->
+- Limit clarifiers to 2–4 items in one level. <!-- QST-STRUCT-TASK-CLARIFIERS-LIMIT -->
+
+### Task code (optional) <!-- group: QST-TASK-CODE -->
+
+Follow the code rules in the Style Guide. <!-- QST-BEHAV-TASK-CODE-REFER-STYLEGUIDE -->
+
+**Example:**
+
+    1. Do this thing...
+
+    ```bash
+    gh workflow run build --repo org/repo
+    ```
+
+### Task screenshot (optional) <!-- group: QST-TASK-IMG -->
+
+Follow the Screenshots rules in the Style Guide. <!-- QST-BEHAV-IMG-REFER-STYLEGUIDE -->
+
+## "Next steps" (optional) <!-- group: QST-NEXT -->
+
+- Use the "Next steps" H2 heading for this section. <!-- QST-STRUCT-NEXT-H2-TEXT -->
+- For each bullet point, write an article title and the link to it. <!-- QST-STRUCT-NEXT-FORMAT -->
+- Write at most three bullet points. <!-- QST-STRUCT-NEXT-3POINTS -->
+- Consider a logical connection from the current quickstart that can act as a basis for users' next learning. <!-- QST-BEHAV-NEXT-logic -->
+
+## Extra content guidelines <!-- group: QST-EXTRA -->
+
+- The entire quickstart should be about 1 200 words long. <!-- QST-BEHAV-EXTRA-LENGTH -->
+- Do not use H4-H6 headings. <!-- QST-STRUCT-FORBID-H4-H6 -->