diff --git a/how-to/about-how-to.md b/how-to/about-how-to.md deleted file mode 100644 index 7f13ac77..00000000 --- a/how-to/about-how-to.md +++ /dev/null @@ -1,67 +0,0 @@ -# The How To article - -How To articles take the reader through a series of steps required to solve a specific problem. -They explain in detail how to do a specific task. -Use How To articles to prescribe a set of sequential steps readers must do to be able to use a feature. -Don't use How To articles to teach concepts. - -How To articles are often confused with tutorials. How To articles are problem-oriented, while tutorials are learning-oriented. - -Readers that have experience with the product and need a specific question answered use How To articles. -New users who want to solve a problem instantly can also benefit, provided the How To is well-written and states any prerequisite knowledge required to complete the task. - -## Content of your How To article - -### The Overview section - -Summarize what the reader will achieve by reading the explanation article: - -* Are you writing for developers or for managers? -* Are you writing for people who have a certain problem to solve? -* Are you writing for a particular industry or market segment? - -Readers should already have read a concept about the topic in an About article. -Ensure you link to the relevant About article in the overview. - -### The Before you start section - -This section prevents readers from getting halfway through and discovering that they need to go and read other documentation before they can continue. -Prerequisites can include other articles or information to read, or it can be technical dependencies such as requiring an internet connection, or particular software. - -Describe what the audience needs to know, or needs to have, before they attempt the How To. -By stating the requirements up-front, you prevent your readers from having a bad experience with your How To. -You can include links to procedures or information, or give useful pointers about how to get what they need. - -For example: - -```markdown -Before you begin, make sure you meet these prerequisites: - -* API credentials for the v3.5 API. For more information about accessing your API credentials, see http://example.com/access_your_api_credentials. -* Access to the Postman application. -* A conceptual understanding about RESTful APIs. For more information, see http://example.com/restful_apis. -* (Optional) A development environment (IDE) that displays API responses formatted for readability. -* A list of favorites prepared, so you can manage them. For more information about favorites lists, see http://example.com/favorite_lists. - -``` - -### The Step-by-step guide sections - -When you are explaining steps in a process, it can be useful to include screenshots for each key part of the process. This can help readers orientate themselves as they move through the steps. It can also help someone who is evaluating the software see how it works without having to install it. - -This section contains a table, which allows you to add a screenshot or call out next to each step. -You can also use an ordered list structure without screenshots in markdown, with HTML tables. - -### The See also section - -It's likely that during the course of explaining a multi-step process you will touch on other topics related to the current one, but not strictly required. -A "See also" section at the end is useful to provide the reader with suggestions on further reading without interrupting the topic covered by the current document. -The distinction between this section and "Before you start" (as outlined above) is that the content in that section is necessary to the current topic, while the reader should be able to complete the How-to without reading the topics in this section. -An example might be setting up an email client, which requires working credentials to an active email address. The reader need not know how to install and run his/her own email server in order to acquire that access, although this is potentially useful. -The link to documentation on running a local mail server could therefore be included in the "See also" section. - -## How To article examples - -* **Example 1**. - -* **Example 2**. diff --git a/how-to/how-to-template-guide.md b/how-to/how-to-template-guide.md new file mode 100644 index 00000000..800077b0 --- /dev/null +++ b/how-to/how-to-template-guide.md @@ -0,0 +1,149 @@ +# How-to guide + +information_source: Read this document before you start working on the [how-to template](how-to-template.md). + +## Introduction + +How-to guide takes your users through a series of steps required to solve a specific problem. It shows your users how to solve a real-world problem or complete a task in your application, like how to create an issue in GitHub. + +The how-to guide clearly describes a set of ordered sequential steps your users must complete to accomplish a task. The how-to guide assumes that a user has basic knowledge of the application and has already read the quickstart and the tutorial. + +Do not use how-to guides to teach concepts. + +How-to guides are often confused with tutorials. How-to guides are task-oriented, while tutorials are learning-oriented. The table below identifies the differences between the two. + +| Tutorials | How-to | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Learning oriented | Task oriented | +| Helps beginners or expert users learn a new feature and provide a successful learning experience. | Helps an expert user accomplish a task or troubleshoot an issue. | +| Follows a carefully managed path, from the start to the end. | Aims for a successful result, and guides the user along the safest, surest way to the goal. | +| Eliminates any unexpected scenarios and provides users with a successful finish. | Alerts the user to the possibility of unexpected scenarios and provides guidance on how to deal with it. | +| Assumes that users do not have any practical knowledge and must explicitly state any tools, file configurations, conceptual details, and so on. | Assumes that users have the practical knowledge of tools, file configurations, applications, and so on. | + +## Why do I need a how-to? + +A how-to guide is often used to help competent users perform a task correctly. It can: + +- Demonstrate to your users the different capabilities of your application +- Guide your users to solve a real-world problem within the application through an ordered series of steps. +- Help answer specific questions that users may have +- Make users comfortable using the application. +- Improve the user experience, and help reduce costs by lowering the number of support requests. + +New users who want to solve a problem instantly can also benefit, provided the how-to is well-written and states any prerequisite knowledge required to complete the task. + +## Before Writing A how-to + +Before you start working on your how-to, identify: + +- The main use cases of your application. +- The different scenarios that your user may encounter in the real world while completing a task. or example, multiple ways through which a task can be completed. If this, then that. In the case of …, an alternative approach is to… +- The surest and the safest way to complete a task. By suggesting multiple ways to complete a task, you're asking users to think through the different ways and choose. Save your users' time and effort by eliminating the options. +- The different error scenarios that a user may encounter while completing a task. and the solutions for the same. + +## Best Practices For Writing A how-to + +1. Prepare your users for the unexpected, alert the user to its possibility and provide guidance on how to deal with it. For example, include callouts such as warnings, caution, or note to communicate important information while completing a task. +2. Use conditional imperatives. If you want x, do y. To achieve w, do z. +3. Do not explain concepts. +4. Do not provide too many links within the guide. Keep your users on a single page as much as possible. Instead, provide links to additional resources at the bottom of the page. +5. Avoid writing guides for edge cases at the outer boundaries of your application’s capability. +6. Test your how-to guide instructions from start to finish so that you can uncover omitted steps, incorrect details, steps out of order, and information gaps that block users. + +## About the "Overview" section + +Use this section to provide the following: + +- A clear description of the problem or the task that the user can solve or complete. +- When and why your user might want to perform the task. For example, in a guide for creating a pull request, you might tell users that pull requests are used to let others know about the changes you have pushed to a branch on a repository. + +Note: The how-to guide assumes that a user has basic knowledge of the application and knows what they want to achieve. + +If there are multiple scenarios under which the task can be completed, then create a table as shown below and hyperlink the different how-to guides available for each scenario. + +| Guide | Scenario | +| --------------------------------- | ---------------------------------------------------- | +| Create a pull request from a fork | The user does not have write permission to the repo. | +| Create a pull request | The user has write permission to the repo. | + +## About the "Before you begin" section + +In this section describe what your users need to know, or need to have before they attempt the how-to. By stating the requirements up-front, you prevent your users from getting halfway through and discovering that they need to go and read other documentation before they can continue. + +Use this section to communicate any prerequisites for this how-to, such as: + +- Familiarity with the application +- Software and tools needed +- Environments to set up and configure +- Authentication and authorization information +- Other guides or information to read +- Links to procedures or information, or any useful pointers about how to get what they need. + +For example: + +```markdown +Before you begin, make sure you meet these prerequisites: + +- API credentials for the v3.5 API. For more information about accessing your API credentials, see http://example.com/access_your_api_credentials. +- Access to the Postman application. +- A conceptual understanding of RESTful APIs. For more information, see http://example.com/restful_apis. +- (Optional) A development environment (IDE) that displays API responses formatted for readability. +- A list of favourites prepared, so you can manage them. For more information about favourites lists, see http://example.com/favorite_lists. +``` + +For easy understanding, consider classifying the prerequisites into different categories such as software prerequisites, and hardware prerequisites. + +Optionally, provide any helpful cues that signal to a user that they’re probably not in the right place and provide them with more suitable options. For example, If you are a Linux user, then refer to {link to relevant Linux how-to guide}. + +## About the "Steps" section + +The steps section is where you describe what the user needs to do. Use an ordered list structure to document the how-to steps. How you write your steps will vary depending on your organization's style guide. The template organizes the steps in the following way: + +{Task name} + +1. {Write the action to take here. Start with a verb.} + + {Optional: Explanatory text} + + {Optional: Code sample or screenshot that helps your users complete this step} + + {Optional: Result} + +### Tips for writing steps + +- For task names, start with a bare infinitive also known as plain form or base form verbs. For example, “connect”, “set up”, or “build” and express the heading as a complete thought. Don't use the -ing form of the verb because it is harder to translate. Instead of saying, "Connect", you might say, "Connect to the VM instance”. +- For each step, optionally provide some background information about the task so users know what they're about to do and why. Continuing with the example, you might provide some best practices for creating memorable repository names. +- Optionally, add a code sample or screenshot after the explanatory text, depending on the type of how-to you're writing. Screenshots are a great way to show specific parts of the screen you are referring to in a step. Make sure your code samples work. +- Remember to orient your users when walking them through each step. If they need to open a particular file or dialogue box to complete the task, provide that information first. +- Provide examples of sample output such as return data, and a message so that the users can validate whether they performed the step correctly or not. Continuing with the example, you might describe what happens after a user clicks the "Create repository" button. +- Use plain language and define the terminology of any technical term next to it. +- Include one action in a step. + +Here is an example step: + +Create repository + +1. Enter a name for your new repository. + Good repository names are short and self-explanatory. Avoid repository names with three or more words. After you click "Create repository", GitHub creates your repository and the main page for the repository is displayed. If needed, you can add substeps below a primary step. Make sure to indent the substep one tab space over if you're using Markdown. + +Create pull request + +1. 2. To create a pull request, do the following: + +a. Navigate to the main page of your repository. + +b. Under your repository name, click **Pull requests**. By default, all open pull requests are displayed. + +c. If you're including code samples in your steps, make sure they are also indented correctly: + +Set your Git username for your repository. You can change the name that is associated with your Git commits using the git config command. git config user.name "Dakota Everson" + +## About the "See also" section + +It's likely that during the course of explaining a multi-task process you will touch on other topics related to the current one, but not strictly required. This section is useful to provide your users with suggestions on further reading without interrupting the topic covered by the current document. An example might be setting up an email client, which requires working credentials to an active email address. The reader need not know how to install and run his/her own email server in order to acquire that access, although this is potentially useful. The link to documentation on running a local mail server could therefore be included in the "See also" section. + +## Additional resources + +[Diataxis framework](https://diataxis.fr/) + +[Docs for Developers](https://docsfordevelopers.com/) diff --git a/how-to/how-to-template.md b/how-to/how-to-template.md new file mode 100644 index 00000000..db5220de --- /dev/null +++ b/how-to/how-to-template.md @@ -0,0 +1,54 @@ + + + +# Title + +::information_source: Before using this template, read the accompanying [how-to template guide](how-to-template-guide.md) + +## Overview + +This guide explains how to {insert a brief description of the task}. + +:information_source: Here are some examples: + +- This guide explains how to comment on a pull request. +- This guide explains how to create or delete a branch on Github. +- This guide explains how to create a repository. + +(Optional) Specify when and why your user might want to perform the task. + +## Before you begin + + + +Before you {insert a brief description of the task}, complete the following prerequisites: + +- Prerequisite 1 +- Prerequisite 2 +- Prerequisite 3 + +## {Task name} + +1. {Write the step here. Use a verb to start.} + +:information_source: You can use this format to describe your step: + +Explanatory text + +(Optional) Code sample or screenshot that helps your users complete this step. + +(Optional) The result of completing this step. + +2. {Write the step here. Use a verb to start.} + + 2.1 {Substep 1} + + 2.2 {Substep 2} + +## See also + +:information_source: Include references and/or links to other related documentation such as how-to guides, conceptual topics, troubleshooting information, and limitation details if any. + +- Reference link +- Concept link +- Troubleshooting link diff --git a/how-to/template-how-to.md b/how-to/template-how-to.md deleted file mode 100644 index d87ba6f0..00000000 --- a/how-to/template-how-to.md +++ /dev/null @@ -1,62 +0,0 @@ - - -# How To template - -## Overview - -Summarize what this How To article is about in a sentence or two. -How To articles primarily include tasks, and answer the question "how do I do it?". - -**Keywords:** Optional: add comma-separated keywords. - -## Before you start - -Before you begin, make sure you meet these prerequisites: - -* Pre-requisite one -* Pre-requisite two - -Include other important information here, such as known issues or bugs. - -## Step-by-step guide - -### Step 1: Optional: Title for step - image or screenshot - - - -![alt text](https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg "Image title that describes image.") - -Brief instructions explaining how to interpret the image. - -### Step 2: Optional: title for step - ordered list - -Lead-in sentence for an ordered list: - -1. Sub-step A -1. Sub-step B -1. Sub-step C - -### Step 3: Optional: title for step - code snippet - -Lead-in sentence explaining the code snippet. For example: - -Run the `apt` command to install the Asciidoctor package and check the version. - -```bash -$ sudo apt install asciidoctor - -$ asciidoctor --version -Asciidoctor 1.5.6.2 [https://asciidoctor.org] -``` - -### Step 4: Optional: title for step - Conclusion - -Provide a summary of the steps completed and explain what the user has achieved by following them. You can also include links to related articles that may help the reader reinforce concepts discussed in this How To article. - -## See also - -Include references and/or links to other related documentation, either internal to the project or external. -After a leading sentence on why/how they are valuable to readers of the current topic, multiple related can be displayed in a list: - -* One list for a small number of items, which can contain internal and external references, or; -* Two lists, divided into internal and external and separated by another leading sentence, if there are a larger number of items.