Skip to content

Commit 676a2ae

Browse files
jorge-campojorge-campo
committed
(#47) fix typo
1 parent 7b2ebc8 commit 676a2ae

File tree

1 file changed

+293
-0
lines changed

1 file changed

+293
-0
lines changed

‎prompts/conversion/markdown-to-json/procedure-template.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
| Section | Format | Required | ID |
2+
|:-------------------------------|:------------------------------|:----------|:------------------------|
3+
| Title | H1 | Yes | `PROC-TITLE` |
4+
| Subtitle | Single bold sentence | Yes | `PROC-SUBTITLE` |
5+
| Access callout | Note-type callout | No | `PROC-ACCESS` |
6+
| Callouts | Tip, Note, Important, Caution | No | `PROC-CALLOUTS` |
7+
| Overview | Paragraph | Yes | `PROC-OVERVIEW` |
8+
| Decisions | Paragraph, list, table | No | `PROC-DECISIONS` |
9+
| Limits | Paragraph, list, table | No | `PROC-LIMITS` |
10+
| Impact | Paragraph, list, table | No | `PROC-IMPACT` |
11+
| Prerequisites | Paragraph, list | No | `PROC-PREREQ` |
12+
| "What to expect" | List | Yes | `PROC-EXPECT` |
13+
| Procedure layout | Flat or sectioned | Yes | `PROC-STRUCT-PATTERN` |
14+
| FAQ / Troubleshooting | Paragraph, list, H3 | No | `PROC-EXTRA` |
15+
| Forbidden content | - | Forbidden | `PROC-FORBID` |
16+
17+
## Front matter
18+
19+
---
20+
title:
21+
doc_type: # [procedure, concept, reference, quickstart, api]
22+
product: # [storage, blockchain, communication]
23+
topics: []
24+
steps_layout: # [flat|sectioned]
25+
authors: # GitHub username
26+
owner: ift
27+
doc_version: # increased by one after every update
28+
slug:
29+
---
30+
31+
## Title <!-- group: PROC-TITLE -->
32+
33+
- Use Markdown H1 headings. <!-- PROC-STRUCT-TITLE-H1 -->
34+
- Aim for 50 to 60 characters; 80 characters maximum. <!-- PROC-BEHAV-TITLE-LENGTH-50-80 -->
35+
- Start with an action verb in the imperative form. Don't use the *-ing* form of the verb. <!-- PROC-BEHAV-TITLE-IMPERATIVE -->
36+
- Capitalize only the first word and any proper nouns (sentence-style capitalization). <!-- PROC-BEHAV-TITLE-SENTENCE-CASE -->
37+
- Focus on the outcome, not the mechanics. Prefer results over lists of actions. For example, instead of "Install Node.js and create a project directory", use "Set up a local development environment for Node.js". <!-- PROC-BEHAV-TITLE-OUTCOME-FOCUSED -->
38+
- Include the action and the object/context (what/where/how) so the goal is unambiguous. <!-- PROC-BEHAV-TITLE-ACTION-OBJECT -->
39+
- Avoid one- or two-word titles and empty verbs like *make*, *manage*, or *put*. <!-- PROC-BEHAV-TITLE-NO-EMPTY-VERBS -->
40+
- Don't use punctuation marks, such as colons, semicolons, or dashes. <!-- PROC-BEHAV-TITLE-NO-PUNCT -->
41+
42+
Examples:
43+
44+
| Usage | Example |
45+
|:--------|:----------------------------------------|
46+
| **Use** | Create a codespace from a template |
47+
| Avoid | Creating a codespace from a template |
48+
| **Use** | Use source control in your codespace |
49+
| Avoid | Use source control |
50+
| **Use** | Collaborate with others in a codespace |
51+
| Avoid | Set up a live share session |
52+
53+
## Subtitle <!-- group: PROC-SUBTITLE -->
54+
55+
- Use a Markdown H4 for the subtitle placed right under the H1. <!-- PROC-STRUCT-SUBTITLE-H4 -->
56+
- One sentence only; no links, lists, or inline formatting. <!-- PROC-BEHAV-SUBTITLE-SINGLE-SENTENCE -->
57+
- Do not end with a period. <!-- PROC-BEHAV-SUBTITLE-NO-PERIOD -->
58+
- Stay under 120 characters (approx. 20 words). <!-- PROC-BEHAV-SUBTITLE-LENGTH-120 -->
59+
- Use an imperative/base-form verb that states the purpose or benefit (for example: *Get started*, *Explore*, *Try*). <!-- PROC-BEHAV-SUBTITLE-IMPERATIVE -->
60+
- Add new value beyond the title; don’t repeat or rephrase the H1. <!-- PROC-BEHAV-SUBTITLE-ADDS-VALUE -->
61+
62+
Examples:
63+
64+
- **Title**: *Quickstart for GitHub Actions* / **Subtitle**: *Try out the core features of GitHub Actions in minutes*
65+
- **Title**: *Create a pull request* / **Subtitle**: *Create a pull request to propose and collaborate on changes to a repository*
66+
67+
## Access callout (optional) <!-- group: PROC-ACCESS -->
68+
69+
This note-type callout is exclusively to alert readers about what roles, permissions, or product versions are required to perform the procedure.
70+
71+
- Place it after the title and subtitle, before the introduction. <!-- PROC-STRUCT-ACCESS-AFTER-SUBTITLE -->
72+
- Use the `Note` callout style. <!-- PROC-STRUCT-ACCESS-NOTE-STYLE -->
73+
- Use label-led, scannable content (no explanations). <!-- PROC-BEHAV-ACCESS-LABELED -->
74+
- Include permissions (software role or permission level). <!-- PROC-BEHAV-ACCESS-PERMISSIONS -->
75+
- Include product (product version or edition), if applicable. <!-- PROC-BEHAV-ACCESS-PRODUCT -->
76+
- If multiple permissions/products apply, use commas. <!-- PROC-BEHAV-ACCESS-LIST-IF-MANY -->
77+
- Do not include knowledge, skills, or required tools. <!-- PROC-BEHAV-ACCESS-SCOPE-ONLY -->
78+
- Omit the callout entirely if no permission/product constraints exist. <!-- PROC-STRUCT-ACCESS-OMIT-IF-EMPTY -->
79+
80+
**Example:**
81+
82+
> **Note**
83+
>
84+
> - **Permissions**: Node operators, Site operators
85+
> - **Product**: Waku v1.4.0 or later
86+
87+
## Callouts <!-- PROC-CALLOUTS -->
88+
89+
- Use callouts sparingly and avoid placing them consecutively. <!-- PROC-STRUCT-CALLOUTS-NOT-CONSECUTIVE -->
90+
- One callout maximum per section <!-- PROC-STRUCT-CALLOUTS-PER-SECTION-ONE -->
91+
- Keep each callout concise (≤ 2 short sentences). If the content needs a list or multiple paragraphs, move it into the body under a heading. <!-- PROC-BEHAV-CALLOUTS-CONCISE -->
92+
- Ensure the callout content is directly relevant to the nearby task or decision point. <!-- PROC-BEHAV-CALLOUTS-RELEVANT -->
93+
- Use the appropriate type: `Tip`, `Note`, `Important`, or `Caution`. <!-- PROC-BEHAV-CALLOUTS-TYPE -->
94+
- 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 -->
95+
- 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 -->
96+
97+
**Example:**
98+
99+
> **Note:**
100+
> Keep container resources within the documented limits to avoid throttling.
101+
102+
## Intro
103+
104+
Every procedure requires an introduction that provides context and helps readers understand the procedure's purpose and scope. The introduction includes these sections, each one represented by a paragraph, list, or table:
105+
106+
- [Overview](#overview)
107+
- [Decisions (optional)](#decisions-optional)
108+
- [Limits (optional)](#limits-optional)
109+
- [Impact (optional)](#impact-optional)
110+
- [Prerequisites (optional)](#prerequisites-optional)
111+
112+
**Examples:**
113+
114+
For an example of a procedure introduction, check out the [procedure example](./procedure-example.md).
115+
116+
### Overview <!-- group: PROC-OVERVIEW -->
117+
118+
- Write a 50–100 word paragraph explaining what this procedure covers, why it matters, and when to use it. <!-- PROC-BEHAV-OVERVIEW-LENGTH-50-100 -->
119+
- Add context that the heading doesn’t provide; do not restate the heading. <!-- PROC-BEHAV-OVERVIEW-NO-REPEAT -->
120+
- State where it applies and who the intended audience is. <!-- PROC-BEHAV-OVERVIEW-AUDIENCE-SCOPE -->
121+
- (Optional) Give one concrete real-world scenario in a single sentence. <!-- PROC-BEHAV-OVERVIEW-EXAMPLE-ONE -->
122+
- Use at most one short alert only if it prevents confusion; otherwise keep this section free of callouts. <!-- PROC-BEHAV-OVERVIEW-ALERT-SPARING -->
123+
124+
### Decisions (optional) <!-- group: PROC-DECISIONS -->
125+
126+
- Summarize decisions the reader must make **before** starting (for example, CLI vs. GUI). <!-- PROC-BEHAV-DECISIONS-PURPOSE -->
127+
- Use a list for simple choices; use a compact table for multi-factor comparisons. <!-- PROC-BEHAV-DECISIONS-FORM -->
128+
- Focus on actionable factors: performance, complexity, cost, prerequisites, and limitations. <!-- PROC-BEHAV-DECISIONS-FACTORS -->
129+
- State trade-offs explicitly (for example, "A is faster but less secure"). <!-- PROC-BEHAV-DECISIONS-TRADEOFFS -->
130+
- Give clear guidance (for example, "Choose A if you need X; choose B if you need Y"). <!-- PROC-BEHAV-DECISIONS-GUIDANCE -->
131+
- If the decision space is complex, link to a dedicated decision guide. <!-- PROC-BEHAV-DECISIONS-LINK -->
132+
133+
### Limits (optional) <!-- group: PROC-LIMITS -->
134+
135+
- Describe constraints as a short paragraph; use a list/table only if it improves scanning. <!-- PROC-BEHAV-LIMITS-FORMAT -->
136+
- Cover quotas, rate limits, timeouts, eventual consistency, and destructive side effects. <!-- PROC-BEHAV-LIMITS-COVERAGE -->
137+
- If a constraint is critical to success or safety, surface it with a single concise callout (see Callouts). <!-- PROC-BEHAV-LIMITS-ALERT-CRITICAL -->
138+
- If useful, mention a workaround or mitigation strategy. <!-- PROC-BEHAV-LIMITS-MITIGATION -->
139+
- Link to a dedicated "Limitations" page if details are lengthy. <!-- PROC-BEHAV-LIMITS-LINK -->
140+
141+
### Impact (optional) <!-- group: PROC-IMPACT -->
142+
143+
- A paragraph, list, or table. <!-- PROC-BEHAV-IMPACT-FORMAT -->
144+
- Highlight side effects and risks (for example, data exposure, downtime, irreversible actions). <!-- PROC-BEHAV-IMPACT-RISKS -->
145+
- Note required privileges or safer alternatives when relevant. <!-- PROC-BEHAV-IMPACT-PRIVS-ALTS -->
146+
- Use a single concise callout for critical security impacts; link out for details. <!-- PROC-BEHAV-IMPACT-ALERT-CRITICAL -->
147+
148+
### Prerequisites (optional) <!-- group: PROC-PREREQ -->
149+
150+
- List only the technical setup needed to run the procedure (software, versions, tools, configuration). <!-- PROC-BEHAV-PREREQ-SCOPE -->
151+
- Don’t include roles, permissions, or product variants here; put those in the [access callout](#access-callout-guidelines). <!-- PROC-BEHAV-PREREQ-NO-ROLES -->
152+
- Prefer a single bullet list of noun phrases; keep it brief and link to install/setup instructions as needed. <!-- PROC-BEHAV-PREREQ-LIST-NOUNS -->
153+
154+
## "What to expect" <!-- group: PROC-EXPECT -->
155+
156+
- Use a Markdown H2 with the exact text "What to expect". <!-- PROC-STRUCT-EXPECT-H2-TEXT -->
157+
- Place this section after the introduction and before the first task section. <!-- PROC-STRUCT-EXPECT-POSITION -->
158+
- Include exactly one unordered list with three items (no code blocks or callouts here). <!-- PROC-STRUCT-EXPECT-UL-THREE -->
159+
- Write one complete sentence per bullet (two short sentences max), and end sentences with a period. <!-- PROC-BEHAV-EXPECT-SENTENCE-1-2 -->
160+
- Use parallel wording in each bullet (same grammatical shape), focused on outcomes users will have after completing the procedure (for example, "You can ..."). <!-- PROC-BEHAV-EXPECT-PARALLEL-OUTCOME -->
161+
- Order items from most important to least important. <!-- PROC-BEHAV-EXPECT-PRIORITY -->
162+
- Avoid links unless you must point to headings in the same page. <!-- PROC-BEHAV-EXPECT-LINKS-INTERNAL -->
163+
164+
**Examples:**
165+
166+
Check out the [procedure example](./procedure-example.md).
167+
168+
## Procedural structure <!-- group: PROC-STRUCT-PATTERN -->
169+
170+
- Choose exactly one layout per article: `flat` or `sectioned`. Do not mix. <!-- PROC-STRUCT-PATTERN-ONE-LAYOUT -->
171+
- Don’t use subtasks. Split into additional H2 tasks (flat) or use the sectioned layout instead. <!-- PROC-STRUCT-PATTERN-NO-SUBTASKS -->
172+
173+
> **Note**
174+
>
175+
> See [Steps structure: flat vs. sectioned](./procedure.md#steps-structure-flat-vs-sectioned) for guidance.
176+
177+
### Procedure layout: flat <!-- group: PROC-STRUCT-FLAT -->
178+
179+
| Element | Format | Required | ID | Rules |
180+
|:---------------|:-------------------------------------|:---------|:---------------------------|:--------------------|
181+
| Task title | H2 | Yes | `PROC-STRUCT-FLAT-TITLE` | PROC-TASK-TITLE |
182+
| Task intro | Paragraph | No | `PROC-STRUCT-FLAT-INTRO` | PROC-TASK-INTRO |
183+
| Task callout | Callout | No | `PROC-STRUCT-FLAT-CALLOUT` | PROC-CALLOUTS |
184+
| Steps list | Numbered list or checkboxes (1) | Yes | `PROC-STRUCT-FLAT-STEPS` | PROC-STEP |
185+
| Clarifiers | Bullets under a step (depth 1) (2) | No | `PROC-STRUCT-FLAT-CLAR` | PROC-CLARIFIERS |
186+
| Code | Fenced code block under the step (3) | No | `PROC-STRUCT-FLAT-CODE` | PROC-CODE |
187+
| Screenshot | Image under the step (3) | No | `PROC-STRUCT-FLAT-IMG` | PROC-SHOT |
188+
189+
(1) Use checkboxes only for unordered or long-running tasks. Numbered lists are the default for procedures.
190+
(2) Use a short bullet list for clarifiers or alternatives. Do not create numbered sub-steps.
191+
(3) Nest code and images inside the list item they clarify (indent so they are children of the preceding step).
192+
193+
> **Note**
194+
>
195+
> The "Rules" column points to the shared rule group that governs this element (see [Procedure guidelines](#procedure-guidelines)).
196+
197+
### Procedure layout: sectioned <!-- group: PROC-STRUCT-SEC -->
198+
199+
| Element (per step) | Format | Required | ID | Rules |
200+
|:-------------------|:--------------------------------|:--------:|:--------------------------|:----------------|
201+
| Step title | H2 `Step {n}: …` | Yes | `PROC-STRUCT-SEC-TITLE` | PROC-TASK-TITLE |
202+
| Step intro | Paragraph | No | `PROC-STRUCT-SEC-INTRO` | PROC-TASK-INTRO |
203+
| Step callout | Callout | No | `PROC-STRUCT-SEC-CALLOUT` | PROC-CALLOUTS |
204+
| Step actions | Numbered list (exactly one) | Yes | `PROC-STRUCT-SEC-STEPS` | PROC-STEP |
205+
| Clarifiers | Bullets under a step (depth 1) | No | `PROC-STRUCT-SEC-CLAR` | PROC-CLARIFIERS |
206+
| Code | Fenced code block under the step| No | `PROC-STRUCT-SEC-CODE` | PROC-CODE |
207+
| Screenshot | Image under the step | No | `PROC-STRUCT-SEC-IMG` | PROC-SHOT |
208+
209+
Additional structural constraints:
210+
211+
- The first section title must be `Step 1:` and subsequent section titles must increment by 1. <!-- PROC-STRUCT-SEC-ORDER-ASC -->
212+
- Each "Step {n}" section contains **exactly one** ordered list of actions. <!-- PROC-STRUCT-SEC-ONE-OL -->
213+
- Do not insert headings, callouts, or tables **between** list items; place them either within the list item they clarify or after the list. <!-- PROC-STRUCT-SEC-NO-HEADINGS-IN-LIST -->
214+
215+
> **Note**
216+
>
217+
> The "Rules" column points to the shared rule group that governs this element (see [Procedure guidelines](#procedure-guidelines)).
218+
219+
## Procedure guidelines
220+
221+
Use these guidelines for both flat and sectioned procedure layouts. <!-- PROC-BEHAV-GUIDE-APPLIES-BOTH -->
222+
223+
### Title guidelines <!-- group: PROC-TASK-TITLE -->
224+
225+
- Procedure section titles are Markdown H2 headings. <!-- PROC-STRUCT-TASK-H2 -->
226+
- In the sectioned layout, prefix with `Step {n}:` starting at 1 and incrementing by 1. <!-- PROC-STRUCT-SEC-H2-STEP-PREFIX -->
227+
- Aim for 50–60 characters; 80 max. <!-- PROC-BEHAV-TASK-TITLE-LENGTH-50-80 -->
228+
- Start with an imperative verb; avoid the -ing form. <!-- PROC-BEHAV-TASK-TITLE-IMPERATIVE -->
229+
- Use sentence case (capitalize only the first word and proper nouns). <!-- PROC-BEHAV-TASK-TITLE-SENTENCE-CASE -->
230+
- Avoid empty verbs (make, manage, put). <!-- PROC-BEHAV-TASK-TITLE-NO-EMPTY-VERBS -->
231+
- Avoid one- or two-word titles. <!-- PROC-BEHAV-TASK-TITLE-NO-ONE-TWO-WORD -->
232+
- Don’t use punctuation marks in titles (colons, semicolons, dashes) except in the sectioned layout (`Step {n}:`). <!-- PROC-BEHAV-TASK-TITLE-NO-PUNCT -->
233+
234+
### Task intro (optional) <!-- group: PROC-TASK-INTRO -->
235+
236+
- Write 1–2 short sentences that provide context. <!-- PROC-BEHAV-TASK-INTRO-BRIEF -->
237+
- Do not repeat the task title wording. <!-- PROC-BEHAV-TASK-INTRO-NO-REPEAT -->
238+
- Add cross-references here, not inside steps. <!-- PROC-BEHAV-TASK-INTRO-LINKS -->
239+
240+
### Task callout (optional) <!-- group: PROC-CALLOUTS -->
241+
242+
- Use one callout after the intro for important notes, warnings, or tips. <!-- PROC-STRUCT-CALLOUTS-AFTER-INTRO -->
243+
- Do not place callouts between steps. <!-- PROC-STRUCT-CALLOUTS-NO-BETWEEN-STEPS -->
244+
- One callout maximum per task. <!-- PROC-STRUCT-CALLOUTS-PER-TASK-ONE -->
245+
246+
### Steps list guidelines <!-- group: PROC-STEP -->
247+
248+
- Use a numbered list when the task is completed in one go. <!-- PROC-BEHAV-STEP-ORDERED-ONEGO -->
249+
- Use checkboxes when steps are unordered or spread over time. <!-- PROC-BEHAV-STEP-CHECKBOX-UNORDERED -->
250+
- Start each step with an imperative verb; avoid -ing forms. <!-- PROC-BEHAV-STEP-IMPERATIVE -->
251+
- One step = one user action (combine only trivial actions). <!-- PROC-BEHAV-STEP-ONE-ACTION -->
252+
- Author ordered lists with `1.` for every item (1, 1, 1 …). <!-- PROC-STRUCT-STEP-OL-ONE -->
253+
- Aim for 2–7 steps. Split if longer. <!-- PROC-BEHAV-STEP-COUNT-2-7 -->
254+
- Avoid one-step tasks. <!-- PROC-BEHAV-STEP-NO-ONE -->
255+
- When adding paragraphs, images, or code under a step, insert a blank line and indent so they are children of that step. <!-- PROC-STRUCT-STEP-NESTING -->
256+
- Bold UI elements (buttons, menus, options). <!-- PROC-BEHAV-STEP-UI-BOLD -->
257+
- Use inline code for commands, filenames, paths, and output. <!-- PROC-BEHAV-STEP-CODE-INLINE -->
258+
- Don’t use external links in steps; only same-page anchors. <!-- PROC-BEHAV-STEP-LINKS-INTERNAL -->
259+
- For UI paths, put location before action. <!-- PROC-BEHAV-STEP-LOCATION-FIRST -->
260+
- For conditions, write the result first, then the condition. <!-- PROC-BEHAV-STEP-RESULT-THEN-CONDITION -->
261+
262+
### Clarifiers (optional) <!-- group: PROC-CLARIFIERS -->
263+
264+
- Don't use numbered substeps beneath a step (nested ordered lists). <!-- PROC-STRUCT-CLARIFIERS-NO-ORDERED -->
265+
- Use bullets for subactions, such as clarifiers or alternatives. <!-- PROC-STRUCT-CLARIFIERS-BULLETS -->
266+
- Limit clarifiers to 2–4 items in one level. <!-- PROC-BEHAV-CLARIFIERS-COUNT-2-4 -->
267+
268+
### Task code (optional) <!-- group: PROC-CODE -->
269+
270+
Follow the code rules in the Style Guide. <!-- PROC-BEHAV-CODE-REFER-STYLEGUIDE -->
271+
272+
**Example:**
273+
274+
1. Do this thing...
275+
276+
```bash
277+
gh workflow run build --repo org/repo
278+
```
279+
280+
## FAQ / Troubleshooting (optional) <!-- group: PROC-EXTRA -->
281+
282+
- Use an H2 Markdown heading for this section. <!-- PROC-STRUCT-EXTRA-H2 -->
283+
- Place this section after the final procedure section and before "Next steps" (if present). <!-- PROC-STRUCT-EXTRA-POSITION -->
284+
- Begin with "Troubleshooting {topic}” for error resolution or "Frequently asked questions" for question-based content. <!-- PROC-BEHAV-EXTRA-TITLE-PATTERN -->
285+
- Use paragraphs, lists, or H3 headings for the content. <!-- PROC-STRUCT-EXTRA-ALLOWED-BLOCKS-H3 -->
286+
- If you use H3 question headings, write them in sentence case and end with a question mark. <!-- PROC-BEHAV-EXTRA-H3-QUESTION-FORM -->
287+
- Use "Frequently asked questions" instead of "FAQ" alone. <!-- PROC-BEHAV-EXTRA-TERM-FAQ -->
288+
- For longer or complex cases, create a separate FAQ or Troubleshooting (concept) article and link to it. <!-- PROC-BEHAV-EXTRA-SPLIT-IF-LONG -->
289+
290+
## Extra content guidelines (forbidden) <!-- group: PROC-FORBID -->
291+
292+
- Do not use H4–H6 headings. <!-- PROC-STRUCT-FORBID-H4-H6 -->
293+
- Do not include a "Further reading" section or links to other related topics at the end of the document. <!-- PROC-BEHAV-FORBID-NO-FURTHER-READING -->

0 commit comments

Comments
 (0)