Skip to content

Commit 50d7586

Browse files
cheny0cheny0
committed
Update
1 parent 4f3cec6 commit 50d7586

File tree

3 files changed

+193
-186
lines changed

3 files changed

+193
-186
lines changed

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

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Quickstart
2+
title: Quickstart for GitHub Repositories
33
topic: Repositories
44
author: jorge-campo, cheny0
55
version: 1
@@ -8,15 +8,13 @@ url: docs/repositories/quickstart
88

99
<!-- This document is an example for the concept template. It is not a real document and should be used for illustration purposes only. -->
1010

11-
# Quickstart
11+
# Quickstart for GitHub Repositories
1212

1313
#### Create and manage your first repository quickly.
1414

1515
> 📒 **Note**
1616
> You can create repositories in your personal account or any organization where you have the required permissions.
1717
18-
## Overview
19-
2018
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.
2119

2220
Repositories are project containers on GitHub. They store source code, configuration, and related files.

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

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
| Section | Format | Required | ID |
2+
|:------------------------------|:------------------------------------|:----------|:---------------------------------|
3+
| Title | H1 | Yes | `QST-TITLE` |
4+
| Subtitle | Single bold sentence | Yes | `QST-SUBTITLE` |
5+
| Access callout | Note-type callout | No | `QST-ACCESS` |
6+
| Callouts | Tip, Note, Important, Caution | No | `QST-CALLOUTS` |
7+
| Overview | Paragraph | Yes | `QST-OVERVIEW` |
8+
| "Before you start" title | H2 | No | `QST-STRUCT-BEFORE-START-H2-TEXT`|
9+
| "Before you start" list | Bullet list | No | `QST-BEFORE-START` |
10+
| Task title | H2 | Yes | `QST-TASK-TITLE` |
11+
| Task intro | Paragraph | No | `QST-TASK-INTRO` |
12+
| Task callout | Callout | No | `QST-TASK-CALLOUTS` |
13+
| Task actions | Numbered list | Yes | `QST-TASK-STEP` |
14+
| Clarifiers | Unordered bullets (depth 1) (2) | No | `QST-TASK-CLARIFIERS` |
15+
| Code | Fenced code block | No | `QST-TASK-CODE` |
16+
| Screenshot | Image | No | `QST-TASK-IMG` |
17+
| H4-H6 headings | - | Forbidden | `QST-STRUCT-FORBID-H4-H6` |
18+
| "Next steps" title | H2 | No | `QST-STRUCT-NEXT-H2-TEXT` |
19+
| "Next steps" list | Bullet list | No | `QST-NEXT` |
20+
21+
## Front matter
22+
---
23+
title:
24+
doc_type: # [procedure, concept, reference, quickstart, api]
25+
product: # [storage, blockchain, communication]
26+
topics: []
27+
authors: # GitHub username
28+
owner: ift
29+
doc_version: # increased by one after every update
30+
slug:
31+
---
32+
33+
## Title <!-- group: QST-TITLE -->
34+
35+
- Use a Markdown H1 heading. <!-- QST-STRUCT-TITLE-H1 -->
36+
- 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 -->
37+
38+
## Subtitle <!-- group: QST-SUBTITLE -->
39+
40+
- Use a Markdown H4 for the subtitle placed right under the H1. <!-- QST-STRUCT-SUBTITLE-H4 -->
41+
- Single sentence with no links, list items, or formatting. Ends with a period. <!-- -BEHAV-SUBTITLE-SINGLE-SENTENCE -->
42+
- Do not end with a period. <!-- QST-BEHAV-SUBTITLE-NO-PERIOD -->
43+
- Stay under 120 characters (approx. 20 words). <!-- QST-BEHAV-SUBTITLE-LENGTH-120 -->
44+
- Use imperative verbs to describe the topic's purpose or benefit: *Explore*, *Get started*, *Try*, and so on. <!-- QST-BEHAV-SUBTITLE-IMPERATIVE -->
45+
- Adds new value beyond the title. It should not repeat the title or be a rephrased version of it. <!-- QST-BEHAV-SUBTITLE-ADDS-VALUE -->
46+
47+
**Examples:**
48+
49+
- *Get hands-on with Waku's key capabilities.*
50+
- *Quickly add payments to your project with Stripe.*
51+
52+
## Access callout <!-- group: QST-ACCESS -->
53+
54+
This note-type callout is exclusively to alert readers about what roles, permissions, or product versions are required to perform the procedure.
55+
56+
- Place it after the title and subtitle, before the overview. <!-- QST-STRUCT-ACCESS-AFTER-SUBTITLE -->
57+
- Use the `Note` callout style. <!-- QST-STRUCT-ACCESS-NOTE-STYLE -->
58+
- Use label-led, scannable content (no explanations). <!-- QST-BEHAV-ACCESS-LABELED -->
59+
- Include permissions (software role or permission level). <!-- QST-BEHAV-ACCESS-PERMISSIONS -->
60+
- Include product (product version or edition), if applicable. <!-- QST-BEHAV-ACCESS-PRODUCT -->
61+
- If multiple permissions/products apply, use commas. <!-- QST-BEHAV-ACCESS-LIST-IF-MANY -->
62+
- Do not include knowledge, skills, or required tools. <!-- QST-BEHAV-ACCESS-SCOPE-ONLY -->
63+
- Omit the callout entirely if no permission/product constraints exist. <!-- QST-STRUCT-ACCESS-OMIT-IF-EMPTY -->
64+
65+
**Examples:**
66+
67+
> **Note**
68+
>
69+
> - **Permissions**: Admin roles with write permissions on the repository
70+
> - **Product**: version 5.0 or later
71+
72+
## Callouts <!-- QST-CALLOUTS -->
73+
74+
- Use callouts sparingly in the document and only when necessary to avoid overwhelming the reader. <!-- QST-STRUCT-CALLOUTS-NOT-CONSECUTIVE -->
75+
- One callout maximum per section <!-- QST-STRUCT-CALLOUTS-PER-SECTION-ONE -->
76+
- 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 -->
77+
- Ensure the callout content is directly relevant to the nearby task or decision point. <!-- QST-BEHAV-CALLOUTS-RELEVANT -->
78+
- Use the appropriate type: `Tip`, `Note`, `Important`, or `Caution`. <!-- QST-BEHAVE-CALLOUTS-TYPE -->
79+
- 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 -->
80+
- 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 -->
81+
82+
## Overview <!-- group: QST-OVERVIEW -->
83+
84+
- Describe the product or feature' core purposes and what the user will achieve in this quickstart. <!-- QST-BEHAV-OVERVIEW-CONTENT -->
85+
- Write one or two 50 to 100-word paragraphs. <!-- QST-BEHAV-OVERVIEW-LENGTH -->
86+
- 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 -->
87+
- Link to related documents or headings in the same document to support the reader's gathering of information. <!-- QST-BEHAV-OVERVIEW-LINK -->
88+
89+
## "Before you start" (optional) <!-- group: QST-BEFORE-START -->
90+
91+
- Use the "Before you start" H2 heading for this section. <!-- QST-STRUCT-BEFORE-START-H2-TEXT -->
92+
- Write a single unordered list. <!-- QST-STRUCT-BEFORE-UNORDERED -->
93+
- Specify the intended audience of this quickstart, required prior knowledge for using this quickstart and the software or hardware requirements. <!-- QST-BEHAV-BEFORE-CONTENT -->
94+
- Use noun phrases (For example, "familiarity with Golang"). Don't include verbs such as "learn" or "prepare". <!-- QST-BEHAV-BEFORE-START-NOUN -->
95+
- 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 -->
96+
- 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 -->
97+
98+
> ⚙️ **Example:**
99+
>
100+
> Before you begin, make sure you have:
101+
>
102+
> - A basic understanding of [Ethereum](https://ethereum.org/en/developers/docs/intro-to-ethereum/) ↗ concepts
103+
> - Knowledge of how to work with Python virtual environments
104+
> - A machine running Ubuntu Linux with the following minimum requirements:
105+
> - 4 GB memory
106+
> - 2 TB SSD
107+
> - Linux 64-bit
108+
109+
## Task guidelines <!-- group: QST-TASK -->
110+
111+
- Choose two or three tasks that are essential, quick to complete, and provide immediate value to the user. <!-- QST-STRUCT-TASK-COUNT -->
112+
- 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 -->
113+
- For the other task(s), focus on the core functionalities of the product or feature. <!-- QST-BEHAV-TASK-CORE-FEATURES -->
114+
115+
### Task title <!-- group: QST-TASK-TITLE -->
116+
117+
- Task titles are Markdown H2 headings. <!-- QST-STRUCT-TASK-TITLE-H2 -->
118+
- Don't include numbering in the title. <!-- QST-BEHAV-TASK-TITLE-NO-NUMBERING -->
119+
- Aim for 50–60 characters; 80 max. <!-- QST-BEHAV-TASK-TITLE-LENGTH -->
120+
- Start with an imperative verb; avoid the *-ing* form. <!-- QST-BEHAV-TASK-TITLE-IMPERATIVE -->
121+
- Use sentence case (capitalize only the first word and proper nouns). <!-- QST-BEHAV-TASK-TITLE-SENTENCE-CASE -->
122+
- Avoid empty verbs (*make*, *manage*, *put*). <!-- QST-BEHAV-TASK-TITLE-NO-EMPTY-VERBS -->
123+
- Avoid one- or two-word titles. <!-- QST-BEHAV-TASK-TITLE-NO-ONE-TWO-WORD -->
124+
- Don't use punctuation marks in titles (colons, semicolons, dashes). <!-- QST-BEHAV-TASK-TITLE-NO-PUNCT -->
125+
B
126+
> ⚙️ **Example:**
127+
>
128+
> - *Run a Waku node*
129+
> - *Connect to the Codex network*
130+
> - *Configure system admin access*
131+
132+
### Task introduction (optional) <!-- group: QST-TASK-INTRO -->
133+
134+
- Write 1–2 short sentences that provide context. <!-- QST-BEHAV-TASK-INTRO-BRIEF -->
135+
- Do not repeat the task title wording. <!-- QST-BEHAV-TASK-INTRO-NO-REPEAT -->
136+
- Add cross-references here, not inside steps. <!-- QST-BEHAV-TASK-INTRO-LINKS -->
137+
138+
### Task callout (optional) <!-- group: QST-TASK-CALLOUTS -->
139+
140+
- Use one callout after the intro for important notes, warnings, or tips. <!-- QST-STRUCT-TASK-CALLOUTS-AFTER-INTRO -->
141+
- Do not place callouts between steps. <!-- QST-STRUCT-TASK-CALLOUTS-NO-BETWEEN-STEPS -->
142+
- One callout maximum per task. <!-- QST-STRUCT-TASK-CALLOUTS-PER-TASK-ONE -->
143+
144+
### Task steps <!-- group: QST-TASK-STEP -->
145+
146+
- Use a numbered list. <!-- QST-BEHAV-TASK-STEP-ORDERED -->
147+
- Start each step with an imperative verb; avoid *-ing* forms. <!-- QST-BEHAV-TASK-STEP-VERB -->
148+
- One step = one user action (combine only trivial actions). <!-- QST-BEHAV-TASK-STEP-ONE-ACTION -->
149+
- All steps must use number `1` (1, 1, 1, ... instead of 1, 2, 3, ...) <!-- QST-BEHAV-TASK-STEP-ALL-ONE -->
150+
- Aim for 2–7 steps. Split if longer. <!-- QST-BEHAV-TASK-STEP-RANGE -->
151+
- Avoid one-step tasks. <!-- QST-BEHAV-TASK-STEP-NO-ONE -->
152+
- 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 -->
153+
- Bold UI elements (buttons, menus, options). <!-- QST-BEHAV-TASK-STEP-UI-BOLD -->
154+
- Use inline code for commands, filenames, paths, and output. <!-- QST-BEHAV-TASK-STEP-CODE-INLINE -->
155+
- Don't use external links in steps; only same-page anchors. <!-- QST-BEHAV-TASK-STEP-LINKS -->
156+
- For UI paths, put location before action. <!-- QST-BEHAV-TASK-STEP-LOC-FIRST -->
157+
- For conditions, write the result first, then the condition. <!-- QST-BEHAV-TASK-STEP-RESULT-FIRST -->
158+
159+
### Clarifiers (optional) <!-- group: QST-TASK-CLARIFIERS -->
160+
161+
- Don't use numbered substeps beneath a step (nested ordered lists). <!-- QST-STRUCT-TASK-CLARIFIERS-NOSUBSTEPS -->
162+
- Use bullets for subactions, such as clarifiers or alternatives. <!-- QST-STRUCT-TASK-CLARIFIERS-BULLETS -->
163+
- Limit clarifiers to 2–4 items in one level. <!-- QST-STRUCT-TASK-CLARIFIERS-LIMIT -->
164+
165+
### Task code (optional) <!-- group: QST-TASK-CODE -->
166+
167+
Follow the code rules in the Style Guide. <!-- QST-BEHAV-TASK-CODE-REFER-STYLEGUIDE -->
168+
169+
**Example:**
170+
171+
1. Do this thing...
172+
173+
```bash
174+
gh workflow run build --repo org/repo
175+
```
176+
177+
### Task screenshot (optional) <!-- group: QST-TASK-IMG -->
178+
179+
Follow the Screenshots rules in the Style Guide. <!-- QST-BEHAV-IMG-REFER-STYLEGUIDE -->
180+
181+
## "Next steps" (optional) <!-- group: QST-NEXT -->
182+
183+
- Use the "Next steps" H2 heading for this section. <!-- QST-STRUCT-NEXT-H2-TEXT -->
184+
- For each bullet point, write an article title and the link to it. <!-- QST-STRUCT-NEXT-FORMAT -->
185+
- Write at most three bullet points. <!-- QST-STRUCT-NEXT-3POINTS -->
186+
- Consider a logical connection from the current quickstart that can act as a basis for users' next learning. <!-- QST-BEHAV-NEXT-logic -->
187+
188+
## Extra content guidelines <!-- group: QST-EXTRA -->
189+
190+
- The entire quickstart should be about 1 200 words long. <!-- QST-BEHAV-EXTRA-LENGTH -->
191+
- Do not use H4-H6 headings. <!-- QST-STRUCT-FORBID-H4-H6 -->

0 commit comments

Comments
 (0)