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..54dfe28 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 @@ -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. diff --git a/manual/2-populate-the-structure/canonical-examples/quickstart-example.md b/manual/2-populate-the-structure/canonical-examples/quickstart-example.md new file mode 100644 index 0000000..2ddb1cf --- /dev/null +++ b/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 +--- + + + +# 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) diff --git a/manual/2-populate-the-structure/canonical-examples/quickstart-example/copy-icon.png b/manual/2-populate-the-structure/canonical-examples/quickstart-example/copy-icon.png new file mode 100644 index 0000000..5c3b188 Binary files /dev/null and b/manual/2-populate-the-structure/canonical-examples/quickstart-example/copy-icon.png differ diff --git a/manual/2-populate-the-structure/canonical-examples/quickstart-example/create-a-repository-step-1.png b/manual/2-populate-the-structure/canonical-examples/quickstart-example/create-a-repository-step-1.png new file mode 100644 index 0000000..dc9db21 Binary files /dev/null and b/manual/2-populate-the-structure/canonical-examples/quickstart-example/create-a-repository-step-1.png differ diff --git a/manual/2-populate-the-structure/canonical-examples/quickstart-example/edit-icon.png b/manual/2-populate-the-structure/canonical-examples/quickstart-example/edit-icon.png new file mode 100644 index 0000000..627d0b8 Binary files /dev/null and b/manual/2-populate-the-structure/canonical-examples/quickstart-example/edit-icon.png differ diff --git a/manual/2-populate-the-structure/canonical-examples/quickstart-example/edit-the-readme-step-3.png b/manual/2-populate-the-structure/canonical-examples/quickstart-example/edit-the-readme-step-3.png new file mode 100644 index 0000000..07dd1b6 Binary files /dev/null and b/manual/2-populate-the-structure/canonical-examples/quickstart-example/edit-the-readme-step-3.png differ diff --git a/manual/2-populate-the-structure/templates/template-quickstart.md b/manual/2-populate-the-structure/templates/template-quickstart.md index e69de29..ff43610 100644 --- a/manual/2-populate-the-structure/templates/template-quickstart.md +++ b/manual/2-populate-the-structure/templates/template-quickstart.md @@ -0,0 +1,182 @@ +| Section | Format | Required | ID | +|:------------------------------|:-----------------------|:---------|:----------------------| +| Title | H1 | Yes | `QST-PAGE-TITLE` | +| Subtitle | Single bold sentence | Yes | `QST-PAGE-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-BEFORE-START-001`| +| "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-CALL` | +| Task actions | Numbered list | Yes | `QST-TASK-STEPS` | +| Clarifiers | Unordered bullets (depth 1) (2) | No | `QST-TASK-BUL` | +| Code | Fenced code block | No | `QST-TASK-CODE` | +| Screenshot | Image | No | `QST-TASK-IMG` | +| H4-H6 headings | - | Forbidden| `QST-EXTRA-002` | +| "Next steps" title | H2 | No | `QST-NEXT-001` | +| "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 guidelines + +- Use a Markdown H1 heading. +- For the title, use the word "Quickstart for" + the name of the project or feature. Do not add other text. For example, "Quickstart for Logos Storage". + +## Subtitle guidelines + +- Single sentence with no links, list items, or formatting. Ends with a period. +- Use bold format. Stay under 120 characters. +- 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 callout guidelines + +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. +- Start with the phrase: *This feature is available to users with...* or *To perform this procedure, you need...* +- Focus on required roles, permissions, or product versions only. Don't include any other prerequisite such as knowledge, skills, or tools. + +**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 + +- Use callouts sparingly in the document and only when necessary to avoid overwhelming the reader. +- One callout maximum per section +- Keep callouts concise. +- Use the appropriate type: `Tip`, `Note`, `Important`, or `Caution`. + +## Overview guidelines + +- 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) guidelines + +- Use the "Before you start" H2 heading for this section. +- Write a single unordered list including: + - The intended audience of this quickstart. + - Required prior knowledge for using this quickstart. + - 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 guidelines + +- 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). + +> ⚙️ **Example:** +> +> - *Run a Waku node* +> - *Connect to the Codex network* +> - *Configure system admin access* + +### Task introduction guidelines (optional) + +- Write 1–2 short sentences that provide context. +- Do not repeat the task title wording. +- Add cross-references here, not inside steps. + +### Task callout guidelines (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 guidelines: + +- Use a numbered list. +- Start each step with an imperative verb; avoid *-ing* forms. +- One step = one user action (combine only trivial actions). +- All steps must use number `1` (1, 1, 1, ... instead of 1, 2, 3, ...) +- 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 guidelines (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 guidelines (optional) + +Follow the code rules in the Style Guide. + +**Example:** + + 1. Do this thing... + + ```bash + gh workflow run build --repo org/repo + ``` + +### Task screenshot guidelines (optional) + +Follow the Screenshots rules in the Style Guide. + +## `Next steps` guidelines (optional) + +- Use the "Next steps" H2 heading for this section. +- Write a bullet list of links to articles about other tasks that the users can try after completing the quickstart. +- Write at most three articles. +- 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.