diff --git a/manual/1-design-the-information/document-types/quickstart-help-me-get-started.md b/manual/1-design-the-information/document-types/quickstart-help-me-get-started.md index 2867657..e69de29 100644 --- a/manual/1-design-the-information/document-types/quickstart-help-me-get-started.md +++ b/manual/1-design-the-information/document-types/quickstart-help-me-get-started.md @@ -1,224 +0,0 @@ -# Quickstart - Help me get started - -> ℹ️ **Note:** -> -> For the template associated to this topic, see [quickstart template](../../../templates/quickstart/quickstart-template.md). - -A quickstart helps your users to start using your product as quickly as possible. It reduces users' onboarding time, giving them the confidence to start working with the product right away. - -A quickstart is more than just an installation guide. Along with helping users set up the product or feature, it should also guide them to try at least one core functionality. - -You need at least one quickstart for each product. If the product is complex, you can create multiple quickstarts for different features or tasks. - -## Write a quickstart - -### Filenames - -Check out the [file names and location rules](../../../CONTRIBUTING.md#file-names-and-location-rules) for more information. - -### General rules - -- The entire quickstart should be about 1 200 words long. -- Include at least one task for users to try the core functionality of the product or feature. -- A quickstart isn’t about explaining every detail, but about helping users quickly accomplish something with your product. For information such as alternative methods or considerations when completing a task, link to a separate [procedure](./procedure-help-me-to-do.md) article. -- Non-procedural information in a quickstart must follow these rules. If any rule fails, move the information to a separate [concept](./concept-help-me-to-understand.md) article. In the quickstart, provide a summary and link to the concept article. - - | Check | Rule | - |:--------|:-----------------------------------------------------------------------------------------------------------------------| - | (R1) Scope | The information only answers: **what** the quickstart or task does, **why** it matters, and **when** to use it. | - | (R2) Length | The information is no longer than 150 words or two short paragraphs. | - | (R3) Structure | The information doesn't contain H3 headings, tables, or diagrams. | - | (R4) Reuse | The information doesn't appear in other documents. | - | (R5) Blocking | Omitting the information would cause immediate failure of the described tasks. | - -## Quickstart structure - -| # | Element | Format | Required | -|:---|:--------------------------------------------------------------|:-----------------------|:---------| -| 1 | [Title](#title) reads "Quickstart" | H1 | Yes | -| 2 | [Subtitle](#subtitle) | H4 | Yes | -| 3 | [Admonition](#admonition-optional) | Information admonition | Yes | -| 4 | ["Overview"](#overview) heading | H2 | Yes | -| 5 | ["Overview"](#overview) content | Paragraph | Yes | -| 6 | ["Before you start"](#before-you-start-section) heading | H2 | No | -| 7 | ["Before you start"](#before-you-start-section) content | Bullet list | No | -| 8 | [Task 1](#task-heading) heading | H2 | Yes | -| 9 | [Task 1](#task-steps) steps | Numbered list | Yes | -| 10 | [Task 1 code sample or image](#code-sample-or-image-optional) | Code block or image | No | -| 11 | [Task 1 subtask](#task-subtask-heading-optional) heading | H3 | No | -| 12 | [Task 1 subtask](#task-subtask-steps-optional) steps | Numbered list | No | -| 13 | [Task 2](#task-2-heading) heading | H2 | Yes | -| 14 | [Task 2](#task-2-steps) steps | Numbered list | Yes | -| 15 | ["Next steps"](#next-steps-optional) heading | H2 | No | -| 16 | ["Next steps"](#next-steps-optional) content | Bullet list | No | - -### Title - -Quickstart titles use only the word "Quickstart" with no additional information. - -### Subtitle - -One short, imperative sentence that expresses the product's or feature's purpose and emphasizes the ease of use. - -Guidelines: - -- Single sentence with no links, list items, or formatting. Ends with a period. -- Use H4 format. Stay under 120 characters / 20 words. -- Use imperative verbs to describe the topic's purpose or benefit: *Explore*, *Get started*, *Try*, and so on. -- Adds new value beyond the title. It should not repeat the title or be a rephrased version of it. - -> ⚙️ **Example:** -> -> - *Get hands-on with Waku’s key capabilities.* -> - *Quickly add payments to your project with Stripe.* - -### Admonition (optional) - -This information-type [admonition](../../20-style-the-content/12-admonitions.md) is exclusively to alert readers about who can use this feature and shouldn't be used for any other information. For example, a feature is only available to specific application role or using a specific tool or interface. - -> ⚙️ **Example:** -> -> *This feature is available to users with the **Admin** role in the application.* - -### Overview - -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. -- 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. - -### "Before you start" section - -This section provides: - -- The intended audience for this document. If you include this information in the [admonition](#admonition-optional) under the subtitle, you can still repeat it here to make sure readers are aware of the document's relevance. -- The basic knowledge that you expect users to have before using this quickstart. -- The software or hardware requirements for the quickstart. - -Guidelines: - -- Use the "Before you start" H2 heading for this section. -- Write a single bullet list of noun phrases. Don't include verbs such as "learn" or "prepare". -- Provide [links](../../20-style-the-content/10-links.md) to related content such as installation instructions or articles that provide required knowledge. -- Setting up or installing prerequisites is not part of a quickstart. 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. - -> ⚙️ **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 section - -Use this section to describe what users need to do. - -Guidelines: - -- Choose two or three tasks that are essential, quick to complete, and provide immediate value to the user. - - The first task is usually about setting up or installing the product or feature. However, if setup is complex, create a separate installation guide and direct readers to it in the [Before you start](#before-you-start-section) section. - - For the other task(s), focus on the core functionalities of the product or feature. -- If your quickstart involves a complex task, break it down into different logical subtasks with each subtask consisting of one or more related steps. -- Describe the most straightforward steps of the tasks. - -#### Task heading - -Guidelines: - -- Don’t include “Task,” “Subtask,” or numbering in the heading. -- Focus on the result, not on the task. -- Start the title with an action verb in the imperative form. Don't use the -ing form of the verb. -- Use H2 headings for each task. -- Use H3 headings for each subtask. -- Avoid H4 headings. Deeper levels (H5, H6) are forbidden. If you need more levels, reorganize the content into more tasks or subtasks. - -> ⚙️ **Example:** -> -> - *Run a Waku node* -> - *Connect to the Codex network* -> - *Configure system admin access* - -#### Task steps - -Guidelines: - -- Optionally, include an introduction paragraph to provide context or required knowledge for the task. -- Include a short description for each step, even when it contains a code sample. -- Provide examples of sample output, such as return data, a message, so that the users can validate whether they perform the step correctly or not. -- Include one action in a step. -- Limit the procedure to a maximum of seven steps. If you need more steps to explain the task, create a subtask. - -> ⚙️ **Example:** -> -> ## Manage files using Codex Vault -> -> You can use Codex Vault, a GUI web application, to manage your files on the Codex testnet. Once you have your Codex node running using the installer, you can access the Codex Vault at https://app.codex.storage. -> -> ### Upload files -> -> 1. Open Codex Vault in your browser. -> 1. In the Upload section, drag and drop your file or click **Upload** to choose it. -> 1. Back up the file CID for download. -> -> ### Download files -> 1. Open Codex Vault in your browser. -> 1. In the Download section, enter the CID of the file you want to download. -> 1. Click **Download**. - -> ℹ️ **Note:** -> -> For additional tips on writing tasks, see [Procedure docs standards](procedure-help-me-to-do.md -). - -#### Code sample or image (optional) - -This section is part of the task steps and doesn't use a heading. - -Use less than two images or code samples per step. If you need more, the step needs splitting. Make sure your code samples and images are up-to-date, functional, and relevant to the task. For more tips, check out [code](../../20-style-the-content/13-code.md) and [images](../../30-work-with-media/02-images.md) guidelines. - -> ℹ️ **Note:** -> -> When you use a code sample or image, it should be indented under the step description so that it's visually grouped with that step. - -#### Task subtask heading (optional) - -Refer to the [task heading](#task-heading) section for guidelines. - -#### Task subtask steps (optional) - -Refer to the [task steps](#task-steps) section for guidelines. - -#### Task 2 heading - -Refer to the [task heading](#task-heading) for guidelines. - -#### Task 2 steps - -Refer to the [task steps](#task-steps) section for guidelines. - -... - -#### Task n heading (optional) - -Refer to the [task heading](#task-heading) for guidelines. - -#### Task n steps (optional) - -Refer to the [task steps](#task-steps) section for guidelines. - -### Next steps (optional) - -Guidelines: - -- Use the "Next steps" H2 heading for this section. -- Use a bullet list to provide at most three links to articles about other tasks that the users can try after completing the quickstart. -- Consider a logical connection from the current quickstart that can act as a basis for your users' next learning. - ---- -*Examples adapted from GitHub Docs (CC BY 4.0). See [Attributions](/ATTRIBUTIONS.md) for details.* diff --git a/manual/2-populate-the-structure/templates/template-quickstart.md b/manual/2-populate-the-structure/canonical-examples/quickstart-example.md similarity index 100% rename from manual/2-populate-the-structure/templates/template-quickstart.md rename to manual/2-populate-the-structure/canonical-examples/quickstart-example.md diff --git a/manual/2-populate-the-structure/templates/quickstart/README.md b/manual/2-populate-the-structure/templates/quickstart/README.md index e69de29..c2299d7 100644 --- a/manual/2-populate-the-structure/templates/quickstart/README.md +++ b/manual/2-populate-the-structure/templates/quickstart/README.md @@ -0,0 +1,50 @@ +# Quickstart + +A quickstart helps your users to start using your product as quickly as possible. It reduces users' onboarding time, giving them the confidence to start working with the product right away. + +A quickstart is more than just an installation guide. Along with helping users set up the product or feature, it should also guide them to try at least one core functionality. + +You need at least one quickstart for each product. If the product is complex, you can create multiple quickstarts for different features or tasks. + +## Quickstart structure + +```markdown +# {Quickstart title} + +{Overview} + +## Before you start + +- {Prerequisite 1} +- {Prerequisite 2} +[...] + +## Task A + +1. {Step 1} +2. {Step 2} + - {Clarifier / Option 1} + - {Clarifier / Option 2} +3. {Step 3} +[...] + +## Task B + +1. {Step 1} +2. {Step 2} +3. {Step 3} +[...] + +## Next steps" +- {Link to related guide 1} +- {Link to related guide 2} +- {Link to related guide 3} +``` + +## Quickstart resources + +| Resource | Description | When to use it | +| :------- | :---------- | :------------- | +| [Quickstart blueprint]() | A visual representation of the quickstart structure and flow. | Use it in task analysis to organize H1 and H2 Markdown headings | +| [Quickstart template](./quickstart-template.md) | A Markdown template with the quickstart structure and basic rules. | Use it to create new quickstart documents. | +| [Quickstart JSON schema](./quickstart-template.json) | A JSON schema that defines the structure and rules for quickstart documents. | Use it to create new quickstart documents with the help of an LLM. | diff --git a/manual/2-populate-the-structure/templates/quickstart/quickstart-template.json b/manual/2-populate-the-structure/templates/quickstart/quickstart-template.json new file mode 100644 index 0000000..0a17e73 --- /dev/null +++ b/manual/2-populate-the-structure/templates/quickstart/quickstart-template.json @@ -0,0 +1,627 @@ +{ + "documentName": "", + "docVersion": null, + "frontMatter": { + "title": null, + "doc_type": null, + "product": null, + "topics": [], + "steps_layout": null, + "authors": [], + "owner": "ift", + "slug": null + }, + "sections": [ + { + "id": "QST-TITLE", + "group": "STRUCT", + "title": "Title", + "required": "required", + "format": "H1", + "rules": [ + { + "id": "QST-STRUCT-TITLE-H1", + "group": "STRUCT", + "description": "Use a Markdown H1 heading.", + "examples": [] + }, + { + "id": "QST-BEHAV-TITLE-IMPERATIVE", + "group": "BEHAV", + "description": "The title consists of the phrase \"Quickstart for\" and the name of the project or feature. Do not add other text.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-SUBTITLE", + "group": "STRUCT", + "title": "Subtitle", + "required": "required", + "format": "Single bold sentence", + "rules": [ + { + "id": "QST-STRUCT-SUBTITLE-H4", + "group": "STRUCT", + "description": "Use a Markdown H4 for the subtitle placed right under the H1.", + "examples": [ + "*Get hands-on with Waku's key capabilities.*", + "*Quickly add payments to your project with Stripe.*" + ] + }, + { + "id": "QST-BEHAV-SUBTITLE-NO-PERIOD", + "group": "BEHAV", + "description": "Do not end with a period.", + "examples": [] + }, + { + "id": "QST-BEHAV-SUBTITLE-LENGTH-120", + "group": "BEHAV", + "description": "Stay under 120 characters (approx. 20 words).", + "examples": [] + }, + { + "id": "QST-BEHAV-SUBTITLE-IMPERATIVE", + "group": "BEHAV", + "description": "Use imperative verbs to describe the topic's purpose or benefit: *Explore*, *Get started*, *Try*, and so on.", + "examples": [] + }, + { + "id": "QST-BEHAV-SUBTITLE-ADDS-VALUE", + "group": "BEHAV", + "description": "Adds new value beyond the title. It should not repeat the title or be a rephrased version of it.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-ACCESS", + "group": "STRUCT", + "title": "Access callouts", + "required": "optional", + "format": "Note-type callout", + "rules": [ + { + "id": "QST-STRUCT-ACCESS-AFTER-SUBTITLE", + "group": "STRUCT", + "description": "Place it after the title and subtitle, before the overview.", + "examples": [ + "Permissions: Admin roles with write permissions on the repository", + "Product: version 5.0 or later" + ] + }, + { + "id": "QST-STRUCT-ACCESS-NOTE-STYLE", + "group": "STRUCT", + "description": "Use the `Note` callout style.", + "examples": [] + }, + { + "id": "QST-BEHAV-ACCESS-LABELED", + "group": "BEHAV", + "description": "Use label-led, scannable content (no explanations).", + "examples": [] + }, + { + "id": "QST-BEHAV-ACCESS-PERMISSIONS", + "group": "BEHAV", + "description": "Include permissions (software role or permission level).", + "examples": [] + }, + { + "id": "QST-BEHAV-ACCESS-PRODUCT", + "group": "BEHAV", + "description": "Include product (product version or edition), if applicable.", + "examples": [] + }, + { + "id": "QST-BEHAV-ACCESS-LIST-IF-MANY", + "group": "BEHAV", + "description": "If multiple permissions/products apply, use commas.", + "examples": [] + }, + { + "id": "QST-BEHAV-ACCESS-SCOPE-ONLY", + "group": "BEHAV", + "description": "Do not include knowledge, skills, or required tools.", + "examples": [] + }, + { + "id": "QST-STRUCT-ACCESS-OMIT-IF-EMPTY", + "group": "STRUCT", + "description": "Omit the callout entirely if no permission/product constraints exist.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-CALLOUTS", + "group": "STRUCT", + "title": "Callouts", + "required": "optional", + "format": "Tip, Note, Important, Caution", + "rules": [ + { + "id": "QST-STRUCT-CALLOUTS-NOT-CONSECUTIVE", + "group": "STRUCT", + "description": "Use callouts sparingly in the document and only when necessary to avoid overwhelming the reader.", + "examples": [] + }, + { + "id": "QST-STRUCT-CALLOUTS-PER-SECTION-ONE", + "group": "STRUCT", + "description": "One callout maximum per section.", + "examples": [] + }, + { + "id": "QST-BEHAV-CALLOUTS-CONCISE", + "group": "BEHAV", + "description": "Keep each callout concise (≤ 2 short sentences). If the content needs a list or multiple paragraphs, move it into the body under a heading.", + "examples": [] + }, + { + "id": "QST-BEHAV-CALLOUTS-RELEVANT", + "group": "BEHAV", + "description": "Ensure the callout content is directly relevant to the nearby task or decision point.", + "examples": [] + }, + { + "id": "QST-BEHAVE-CALLOUTS-TYPE", + "group": "BEHAV", + "description": "Use the appropriate type: `Tip`, `Note`, `Important`, or `Caution`.", + "examples": [] + }, + { + "id": "PROC-BEHAV-CALLOUTS-NO-STEPS", + "group": "BEHAV", + "description": "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.\"", + "examples": [] + }, + { + "id": "PROC-BEHAV-CALLOUTS-TYPES-REFER-STYLEGUIDE", + "group": "BEHAV", + "description": "For the allowed callout types and when to use them, see the [writing rules](../../3-validating-design/writing-rules/README.md).", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-OVERVIEW", + "group": "BEHAV", + "title": "Overview", + "required": "required", + "format": "Paragraph", + "rules": [ + { + "id": "QST-BEHAV-OVERVIEW-CONTENT", + "group": "BEHAV", + "description": "Describe the product or feature' core purposes and what the user will achieve in this quickstart.", + "examples": [] + }, + { + "id": "QST-BEHAV-OVERVIEW-LENGTH", + "group": "BEHAV", + "description": "Write one or two 50 to 100-word paragraphs.", + "examples": [] + }, + { + "id": "QST-BEHAV-OVERVIEW-MORE-INFO", + "group": "BEHAV", + "description": "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.", + "examples": [] + }, + { + "id": "QST-BEHAV-OVERVIEW-LINK", + "group": "BEHAV", + "description": "Link to related documents or headings in the same document to support the reader's gathering of information.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-BEFORE-START", + "group": "STRUCT", + "title": "\"Before you start\"", + "required": "optional", + "format": "Bullet list", + "rules": [ + { + "id": "QST-STRUCT-BEFORE-START-H2-TEXT", + "group": "STRUCT", + "description": "Use the \"Before you start\" H2 heading for this section.", + "examples": [ + "A basic understanding of Ethereum concepts", + "Knowledge of how to work with Python virtual environments" + ] + }, + { + "id": "QST-STRUCT-BEFORE-UNORDERED", + "group": "STRUCT", + "description": "Write a single unordered list.", + "examples": [] + }, + { + "id": "QST-BEHAV-BEFORE-CONTENT", + "group": "BEHAV", + "description": "Specify the intended audience of this quickstart, required prior knowledge for using this quickstart and the software or hardware requirements.", + "examples": [] + }, + { + "id": "QST-BEHAV-BEFORE-START-NOUN", + "group": "BEHAV", + "description": "Use noun phrases. Don't include verbs such as \"learn\" or \"prepare\".", + "examples": [] + }, + { + "id": "QST-BEHAV-BEFORE-START-LINK", + "group": "BEHAV", + "description": "Provide [links](../../20-style-the-content/10-links.md) to related content such as installation instructions or articles that provide required knowledge.", + "examples": [] + }, + { + "id": "QST-BEHAV-BEFORE-START-NO-STEPS", + "group": "BEHAV", + "description": "Don't include the procedure for setting up or installing prerequisites. If you must explain the procedure, link to the corresponding document or resource.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-TASK-TITLE", + "group": "STRUCT", + "title": "Task title", + "required": "required", + "format": "H2", + "rules": [ + { + "id": "QST-STRUCT-TASK-COUNT", + "group": "STRUCT", + "description": "Choose two or three tasks that are essential, quick to complete, and provide immediate value to the user.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-SETUP", + "group": "BEHAV", + "description": "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.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-CORE-FEATURES", + "group": "BEHAV", + "description": "For the other task(s), focus on the core functionalities of the product or feature.", + "examples": [] + }, + { + "id": "QST-STRUCT-TASK-TITLE-H2", + "group": "STRUCT", + "description": "Task titles are Markdown H2 headings.", + "examples": [ + "Run a Waku node", + "Connect to the Codex network" + ] + }, + { + "id": "QST-BEHAV-TASK-TITLE-NO-NUMBERING", + "group": "BEHAV", + "description": "Don't include numbering in the title.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-TITLE-LENGTH", + "group": "BEHAV", + "description": "Aim for 50–60 characters; 80 max.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-TITLE-IMPERATIVE", + "group": "BEHAV", + "description": "Start with an imperative verb; avoid the -ing form.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-TITLE-SENTENCE-CASE", + "group": "BEHAV", + "description": "Use sentence case (capitalize only the first word and proper nouns).", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-TITLE-NO-EMPTY-VERBS", + "group": "BEHAV", + "description": "Avoid empty verbs (*make*, *manage*, *put*).", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-TITLE-NO-ONE-TWO-WORD", + "group": "BEHAV", + "description": "Avoid one- or two-word titles.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-TITLE-NO-PUNCT", + "group": "BEHAV", + "description": "Don't use punctuation marks in titles (colons, semicolons, dashes).", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-TASK-INTRO", + "group": "BEHAV", + "title": "Task intro", + "required": "optional", + "format": "Paragraph", + "rules": [ + { + "id": "QST-BEHAV-TASK-INTRO-BRIEF", + "group": "BEHAV", + "description": "Write 1–2 short sentences that provide context.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-INTRO-NO-REPEAT", + "group": "BEHAV", + "description": "Do not repeat the task title wording.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-INTRO-LINKS", + "group": "BEHAV", + "description": "Add cross-references here, not inside steps.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-TASK-CALLOUTS", + "group": "STRUCT", + "title": "Task callouts", + "required": "optional", + "format": "Callout", + "rules": [ + { + "id": "QST-STRUCT-TASK-CALLOUTS-AFTER-INTRO", + "group": "STRUCT", + "description": "Use one callout after the intro for important notes, warnings, or tips.", + "examples": [] + }, + { + "id": "QST-STRUCT-TASK-CALLOUTS-NO-BETWEEN-STEPS", + "group": "STRUCT", + "description": "Do not place callouts between steps.", + "examples": [] + }, + { + "id": "QST-STRUCT-TASK-CALLOUTS-PER-TASK-ONE", + "group": "STRUCT", + "description": "One callout maximum per task.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-TASK-STEP", + "group": "STRUCT", + "title": "Task actions", + "required": "required", + "format": "Numbered list", + "rules": [ + { + "id": "QST-BEHAV-TASK-STEP-ORDERED", + "group": "BEHAV", + "description": "Use a numbered list.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-VERB", + "group": "BEHAV", + "description": "Start each step with an imperative verb; avoid -ing forms.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-ONE-ACTION", + "group": "BEHAV", + "description": "One step = one user action (combine only trivial actions).", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-RANGE", + "group": "BEHAV", + "description": "Aim for 2–7 steps. Split if longer.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-NO-ONE", + "group": "BEHAV", + "description": "Avoid one-step tasks.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-BLOCKS", + "group": "BEHAV", + "description": "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.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-UI-BOLD", + "group": "BEHAV", + "description": "Bold UI elements (buttons, menus, options).", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-CODE-INLINE", + "group": "BEHAV", + "description": "Use inline code for commands, filenames, paths, and output.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-LINKS", + "group": "BEHAV", + "description": "Don't use external links in steps; only same-page anchors.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-LOC-FIRST", + "group": "BEHAV", + "description": "For UI paths, put location before action.", + "examples": [] + }, + { + "id": "QST-BEHAV-TASK-STEP-RESULT-FIRST", + "group": "BEHAV", + "description": "For conditions, write the result first, then the condition.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-TASK-CLARIFIERS", + "group": "STRUCT", + "title": "Clarifiers", + "required": "optional", + "format": "Unordered bullets (depth 1) (2)", + "rules": [ + { + "id": "QST-STRUCT-TASK-CLARIFIERS-NOSUBSTEPS", + "group": "STRUCT", + "description": "Don't use numbered substeps beneath a step (nested ordered lists).", + "examples": [] + }, + { + "id": "QST-STRUCT-TASK-CLARIFIERS-BULLETS", + "group": "STRUCT", + "description": "Use bullets for subactions, such as clarifiers or alternatives.", + "examples": [] + }, + { + "id": "QST-STRUCT-TASK-CLARIFIERS-LIMIT", + "group": "STRUCT", + "description": "Limit clarifiers to 2–4 items in one level.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-TASK-CODE", + "group": "BEHAV", + "title": "Code", + "required": "optional", + "format": "Fenced code block", + "rules": [ + { + "id": "QST-BEHAV-TASK-CODE-REFER-STYLEGUIDE", + "group": "BEHAV", + "description": "Follow the code rules in the Style Guide.", + "examples": [ + "`gh workflow run build --repo org/repo`" + ] + } + ], + "examples": [] + }, + { + "id": "QST-TASK-IMG", + "group": "BEHAV", + "title": "Screenshot", + "required": "optional", + "format": "Image", + "rules": [ + { + "id": "QST-BEHAV-IMG-REFER-STYLEGUIDE", + "group": "BEHAV", + "description": "Follow the Screenshots rules in the Style Guide.", + "examples": [] + } + ], + "examples": [] + }, + { + "id": "QST-STRUCT-FORBID-H4-H6", + "group": "STRUCT", + "title": "H4-H6 headings", + "required": "forbidden", + "format": "-", + "rules": [], + "examples": [] + }, + { + "id": "QST-STRUCT-NEXT-H2-TEXT", + "group": "STRUCT", + "title": "\"Next steps\" title", + "required": "optional", + "format": "H2", + "rules": [], + "examples": [] + }, + { + "id": "QST-NEXT", + "group": "STRUCT", + "title": "\"Next steps\" list", + "required": "optional", + "format": "Bullet list", + "rules": [ + { + "id": "QST-STRUCT-NEXT-H2-TEXT", + "group": "STRUCT", + "description": "Use the \"Next steps\" H2 heading for this section.", + "examples": [] + }, + { + "id": "QST-STRUCT-NEXT-FORMAT", + "group": "STRUCT", + "description": "For each bullet point, write an article title and the link to it.", + "examples": [] + }, + { + "id": "QST-STRUCT-NEXT-3POINTS", + "group": "STRUCT", + "description": "Write at most three bullet points.", + "examples": [] + }, + { + "id": "QST-BEHAV-NEXT-LOGIC", + "group": "BEHAV", + "description": "Consider a logical connection from the current quickstart that can act as a basis for users' next learning.", + "examples": [] + }, + { + "id": "QST-BEHAV-EXTRA-LENGTH", + "group": "BEHAV", + "description": "The entire quickstart should be about 1 200 words long.", + "examples": [] + } + ], + "examples": [] + } + ], + "forbidden": [ + { + "id": "QST-EXTRA", + "rules": [ + { + "id": "QST-STRUCT-FORBID-H4-H6", + "group": "FORBID", + "description": "Do not use H4-H6 headings." + } + ] + } + ], + "validation": { + "missingRuleIds": [], + "duplicateRuleIds": [], + "groupViolations": [], + "forbiddenViolations": [], + "notes": [] + } +} \ No newline at end of file diff --git a/manual/2-populate-the-structure/templates/quickstart/quickstart-template.md b/manual/2-populate-the-structure/templates/quickstart/quickstart-template.md index e69de29..f24b81d 100644 --- a/manual/2-populate-the-structure/templates/quickstart/quickstart-template.md +++ b/manual/2-populate-the-structure/templates/quickstart/quickstart-template.md @@ -0,0 +1,188 @@ +| Section | Format | Required | ID | +|:------------------------------|:------------------------------------|:----------|:---------------------------------| +| Title | H1 | Yes | `QST-TITLE` | +| Subtitle | Single bold sentence | Yes | `QST-SUBTITLE` | +| Access callouts | Note-type callout | No | `QST-ACCESS` | +| Callouts | Tip, Note, Important, Caution | No | `QST-CALLOUTS` | +| Overview | Paragraph | Yes | `QST-OVERVIEW` | +| "Before you start" | Bullet list | No | `QST-BEFORE-START` | +| Task title | H2 | Yes | `QST-TASK-TITLE` | +| Task intro | Paragraph | No | `QST-TASK-INTRO` | +| Task callouts | 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" | 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 + +- Use a Markdown H1 heading. +- The title consists of the phrase "Quickstart for" and the name of the project or feature. For example, "Quickstart for Logos Storage". Do not add other text. + +## Subtitle + +- Use a Markdown H4 for the subtitle placed right under the H1. +- Single sentence with no links, list items, or formatting. Ends with a period. +- Do not end with a period. +- Stay under 120 characters (approx. 20 words). +- Use imperative verbs to describe the topic's purpose or benefit: *Explore*, *Get started*, *Try*, and so on. +- Adds new value beyond the title. It should not repeat the title or be a rephrased version of it. + +**Examples:** + +- *Get hands-on with Waku's key capabilities.* +- *Quickly add payments to your project with Stripe.* + +## Access callouts + +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. +- Use the `Note` callout style. +- Use label-led, scannable content (no explanations). +- Include permissions (software role or permission level). +- Include product (product version or edition), if applicable. +- If multiple permissions/products apply, use commas. +- Do not include knowledge, skills, or required tools. +- Omit the callout entirely if no permission/product constraints exist. + +**Examples:** + + > **Note** + > + > - **Permissions**: Admin roles with write permissions on the repository + > - **Product**: version 5.0 or later + +## Callouts + +- Use callouts sparingly in the document and only when necessary to avoid overwhelming the reader. +- One callout maximum per section +- Keep each callout concise (≤ 2 short sentences). If the content needs a list or multiple paragraphs, move it into the body under a heading. +- Ensure the callout content is directly relevant to the nearby task or decision point. +- Use the appropriate type: `Tip`, `Note`, `Important`, or `Caution`. +- 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." +- For the allowed callout types and when to use them, see the [writing rules](../../3-validating-design/writing-rules/README.md). + +## Overview + +- Describe the product or feature' core purposes and what the user will achieve in this quickstart. +- Write one or two 50 to 100-word paragraphs. +- 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. +- Link to related documents or headings in the same document to support the reader's gathering of information. + +## "Before you start" (optional) + +- Use the "Before you start" H2 heading for this section. +- Write a single unordered list. +- Specify the intended audience of this quickstart, required prior knowledge for using this quickstart and the software or hardware requirements. +- Use noun phrases (For example, "familiarity with Golang"). Don't include verbs such as "learn" or "prepare". +- Provide [links](../../20-style-the-content/10-links.md) to related content such as installation instructions or articles that provide required knowledge. +- Don't include the procedure for setting up or installing prerequisites. If you must explain the procedure, link to the corresponding document or resource. + +> ⚙️ **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 + +- Choose two or three tasks that are essential, quick to complete, and provide immediate value to the user. + - 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. + - For the other task(s), focus on the core functionalities of the product or feature. + +### Task title + +- Task titles are Markdown H2 headings. +- Don't include numbering in the title. +- Aim for 50–60 characters; 80 max. +- Start with an imperative verb; avoid the *-ing* form. +- Use sentence case (capitalize only the first word and proper nouns). +- Avoid empty verbs (*make*, *manage*, *put*). +- Avoid one- or two-word titles. +- Don't use punctuation marks in titles (colons, semicolons, dashes). +B +> ⚙️ **Example:** +> +> - *Run a Waku node* +> - *Connect to the Codex network* +> - *Configure system admin access* + +### Task introduction (optional) + +- Write 1–2 short sentences that provide context. +- Do not repeat the task title wording. +- Add cross-references here, not inside steps. + +### Task callouts (optional) + +- Use one callout after the intro for important notes, warnings, or tips. +- Do not place callouts between steps. +- One callout maximum per task. + +### Task steps + +- Use a numbered list. +- Start each step with an imperative verb; avoid *-ing* forms. +- One step = one user action (combine only trivial actions). +- Aim for 2–7 steps. Split if longer. +- Avoid one-step tasks. +- 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. +- Bold UI elements (buttons, menus, options). +- Use inline code for commands, filenames, paths, and output. +- Don't use external links in steps; only same-page anchors. +- For UI paths, put location before action. +- For conditions, write the result first, then the condition. + +### Clarifiers (optional) + +- Don't use numbered substeps beneath a step (nested ordered lists). +- Use bullets for subactions, such as clarifiers or alternatives. +- Limit clarifiers to 2–4 items in one level. + +### Task code (optional) + +Follow the code rules in the Style Guide. + +**Example:** + + 1. Do this thing... + + ```bash + gh workflow run build --repo org/repo + ``` + +### Task screenshot (optional) + +Follow the Screenshots rules in the Style Guide. + +## "Next steps" (optional) + +- Use the "Next steps" H2 heading for this section. +- For each bullet point, write an article title and the link to it. +- Write at most three bullet points. +- Consider a logical connection from the current quickstart that can act as a basis for users' next learning. + +## Extra content guidelines + +- The entire quickstart should be about 1 200 words long. +- Do not use H4-H6 headings.