New How-to template #265
New How-to template #265
Conversation
|
|
||
| # Title | ||
|
|
||
| ::information_source: Before using this template, read the accompanying [how-to template guide](how-to-template-guide.md) |
There was a problem hiding this comment.
nitpick: A colon (:) appears at the beginning of the sentence in the output.
| 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… |
There was a problem hiding this comment.
| - 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 different scenarios that your user may encounter in the real world while completing a task. If this, then that. In the case of …, an alternative approach is to… |
| @@ -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). | |||
There was a problem hiding this comment.
nitpick: The emoji did not render correctly. I believe a colon needs to be added before information_source.
| - 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. |
There was a problem hiding this comment.
| Note: The how-to guide assumes that a user has basic knowledge of the application and knows what they want to achieve. | |
| ℹ️ The how-to guide assumes that a user has basic knowledge of the application and knows what they want to achieve. |
|
|
||
| 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. |
There was a problem hiding this comment.
Could link to tutorial template here
|
|
||
| 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 |
There was a problem hiding this comment.
| - Demonstrate to your users the different capabilities of your application | |
| - Demonstrate to your users the different capabilities of your application. |
|
|
||
| - 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 |
There was a problem hiding this comment.
| - Help answer specific questions that users may have | |
| - Help answer specific questions that users may have. |
|
|
||
| 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 | |
There was a problem hiding this comment.
praise: I really like the table and your breakdown on the differences between how-tos and tutorials. It provides a clear understanding of how tutorials and how-tos are different. Great job!
There was a problem hiding this comment.
praise/thought: The how-to vs tutorial table is great. It would probably be worth:
- Including the same table in the tutorial template
- Introducing a quickstart vs tutorial comparison into the quickstart and tutorial templates.
(This is not an action for this PR.)
| @@ -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). | |||
There was a problem hiding this comment.
| information_source: Read this document before you start working on the [how-to template](how-to-template.md). | |
| :information_source: Read this document before you start working on the [how-to template](how-to-template.md). |
| - 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. |
There was a problem hiding this comment.
| - 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. | |
| - Remember to orient your users when walking them through each step. If they need to open a particular file or dialog box to complete the task, provide that information first. |
| - 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. |
There was a problem hiding this comment.
question: Can you clarify what your second sentence in the last bullet point means?
There was a problem hiding this comment.
It was a typo and has been rectified now. Thanks for pointing this out.
|
|
||
| 2.2 {Substep 2} | ||
|
|
||
| ## See also |
There was a problem hiding this comment.
suggestion, non-blocking: 'See also' and 'Additional resources' could be written exactly the same - DITA uses Related topics (or links) - maybe this is a question for the style guide.
|
|
||
| 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. |
There was a problem hiding this comment.
nitpick (non-blocking): You probably don't need to say 'ordered' and 'sequential', just one suffices.
There was a problem hiding this comment.
We've removed the ordered and going with just sequential, thanks.
|
|
||
| information_source: Read this document before you start working on the [how-to template](how-to-template.md). | ||
|
|
||
| ## Introduction |
There was a problem hiding this comment.
suggestion (non-blocking): I'd probably renamed this section to 'When to use/write a how-to guide'.
|
|
||
| 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. |
There was a problem hiding this comment.
Absolutely loved this section! It makes a great comparison.
|
|
||
| ## Why do I need a how-to? | ||
|
|
||
| A how-to guide is often used to help competent users perform a task correctly. It can: |
There was a problem hiding this comment.
nitpick (non-blocking): I'd delete 'competent' because if the user can't perform the task correctly, then it might imply incompetence.
There was a problem hiding this comment.
Replaced competent with advanced, thanks for pointing it out.
| | 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? |
There was a problem hiding this comment.
nitpick (non-blocking): I'd probably write 'how-to' or 'how-to guide' consistently throughout the text.
|
|
||
| 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 |
There was a problem hiding this comment.
nitpick (non-blocking): Alternates between sentence-case and title case throughout the text.
|
|
||
| ## 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. |
There was a problem hiding this comment.
nitpick (non-blocking): This should probably be a bullet list, since there is no particular order.
|
I am not 100% sure how to use github but I would like to ask if an Additional Resources section of Useful Links is required. I have taken the list from the previously shared Google Doc and formatted below. Additional ResourcesBhatti, J., Corleissen, Z.S., Lambourne, J., Nunez, D. And Waterhouse, H. 2021. Docs for Developers: An Engineer’s Field Guide to Technical Writing 1st ed. Edition. Diátaxis. 2017. A systematic framework for technical documentation authoring. https://diataxis.fr/ Useful linksCurrent How-to template Diátaxis. framework Quickstart template The Good Docs contributing guide Tutorial template Anbox Cloud. How to create an application Charmed Kubeflow. How to install Kubeflow v1.4 Divio How-to guides Google Cloud Resource Manager Documentation Google Compute Engine documentation Google developer documentation style guide/. Procedures. openstack How-to guides The jupyter-book repository! Ubuntu Core How-to guides |
| :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. |
There was a problem hiding this comment.
I believe GitHub should be with a capital H.
|
|
||
| | Tutorials | How-to | | ||
| | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | ||
| | Learning oriented | Task oriented | |
There was a problem hiding this comment.
Learning oriented / task oriented
In my opinion, this items are not self explanatory enough. Can be definitely combined with the next row in a manner like Learning oriented: helps beginners or expert users learn a new feature and provide a successful learning experience.
| | 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? |
There was a problem hiding this comment.
how-to should be capitalised in this header and others: 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… |
There was a problem hiding this comment.
If this, then that. In the case of …, an alternative approach is to…
Seems it can be a 2nd level bulleted list of items
|
|
||
| Create pull request | ||
|
|
||
| 1. 2. To create a pull request, do the following: |
There was a problem hiding this comment.
Comment (blocking): Agreed. Something about the formatting is off here in this whole section. Double-check that you've got it right.
There was a problem hiding this comment.
Praise: You've made such good progress even in the two weeks since I last looked at the template. Great work @OphyBoamah and @gayathri-krishnaswamy . Super impressive!
| 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. |
There was a problem hiding this comment.
Comment (non-blocking): I think I disagree slightly with the suggestion to avoid having too many links in the guide and to instead put them at the end. While I definitely agree that you don't want to over-link throughout the whole guide, sometimes a well placed link for more information can be really valuable when you think the user might legitimately need it.
Maybe I'd rephrase this as: "Sometimes it's helpful to occasionally provide links to supporting pieces of documentation for more information--especially when the user might need a link to supporting reference materials or background information. However, avoid providing too many links within the guide. ..." With the rest of the phrase the way you have it.
| 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. |
There was a problem hiding this comment.
Suggestion (rephrasing, non-blocking): I'd maybe rephrase best practice #5. Here's my suggested edit: "Keep your documentation simple and avoid over-documenting multiple ways of achieving the same task. Sometimes there is more than one way to complete a given task. In that scenario, you should pick the most common or recommended method of completing a task and only document that one path. Additional methods should be omitted or mentioned by providing a link or reference document. Also, avoid writing edge cases at the boundaries of your application's capability."
| 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. |
There was a problem hiding this comment.
Suggestion (non-blocking): I think we should probably mention more in this document that it's extremely important to ensure that your how-to guide is technically accurate. This best practice could be a good place to emphasize that point. A possible rewrite: "It's important to ensure that the steps provided in your how-to guide are technically accurate. Where possible, try to test your how-to guide instructions yourself from start to finish to verify that your documentation doesn't have any missing steps, incorrect details, steps out of order, or other potential blocking issues. If it's not possible to test it yourself, have a developer or subject matter expert demonstrate the step to you and record the session, if possible."
| - 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. |
There was a problem hiding this comment.
Praise: I love this new section you've recently added to the guide. It's really great and it's a big improvement to the draft!
Suggestion (non-blocking): I think I still want a little bit more in this section, though. For example, I feel like we're missing some information about how to write conditional steps and how to format sub-steps.
It also occurred to me that it could be worth advising them to check their organization's style guide for guidance about how steps should be written and formatted, if they have those guidelines.
|
|
||
| Create pull request | ||
|
|
||
| 1. 2. To create a pull request, do the following: |
There was a problem hiding this comment.
Comment (blocking): Agreed. Something about the formatting is off here in this whole section. Double-check that you've got it right.
| 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. |
There was a problem hiding this comment.
Comment (non-blocking): Usually I add a line break and indent this content when I'm formatting a step that includes an explanation like this. I think that makes it more readable and I see that recommendation in multiple style guides. Is there a way to get that here in a Markdown file? And is there a way to call that out to readers?
|
|
||
| [Diataxis framework](https://diataxis.fr/) | ||
|
|
||
| [Docs for Developers](https://docsfordevelopers.com/) |
There was a problem hiding this comment.
Comment (non-blocking): I like the resources that you've listed here, but perhaps you could explain why you recommend reading them.
Also, I'd like to recommend adding an additional resource here. I like IBM"s Developing Quality Technical Information, 3rd ed. I especially think Chapter 3, Task orientation is a great guide on how to effectively write steps. It includes many helpful examples of good and bad task writing.
The section about lists in the Google Developer's Style Guide is also really helpful. Other online style guides might be good.
| @@ -0,0 +1,54 @@ | |||
| <!-- Copy this Template. --> | |||
There was a problem hiding this comment.
Suggestion (non-blocking): We probably don't need "copy this template" advice, as it is likely obvious to the reader. (We should aim to be concise.)
| @@ -0,0 +1,54 @@ | |||
| <!-- Copy this Template. --> | |||
| <!-- Describe the title of your article by replacing "How To Template" with the page name you want to publish to. --> | |||
There was a problem hiding this comment.
| <!-- Describe the title of your article by replacing "How To Template" with the page name you want to publish to. --> |
Suggestion (non-blocking): Suggest that we don't need this advice, especially if we use a convention of putting variables inside curly brackets.
| <!-- Copy this Template. --> | ||
| <!-- Describe the title of your article by replacing "How To Template" with the page name you want to publish to. --> | ||
|
|
||
| # Title |
There was a problem hiding this comment.
| # Title | |
| # {Title} |
Suggestion (non-blocking): Suggest that all variables be put inside curly brackets. This is something we should confirm with our style committee.
|
|
||
| # Title | ||
|
|
||
| ::information_source: Before using this template, read the accompanying [how-to template guide](how-to-template-guide.md) |
There was a problem hiding this comment.
Suggestion (non-blocking): We should be consistent with other templates regarding our standard format and advice. For instance, https://raw.githubusercontent.com/thegooddocsproject/templates/dev/quickstarts/quickstart-template.md has this sentence right at the top.
Suggest going through the other published templates and looking to make sure we are aligned.
| @@ -0,0 +1,54 @@ | |||
| <!-- Copy this Template. --> | |||
There was a problem hiding this comment.
Suggestion (non-blocking): We should be consistent with other templates regarding our standard advice.
Suggest looking at other published templates, and adopting the same conventions.
|
|
||
| (Optional) Code sample or screenshot that helps your users complete this step. | ||
|
|
||
| (Optional) The result of completing this step. |
There was a problem hiding this comment.
suggestion: An example will likely be very valuable here (or in the guide). Something like:
- Notice {button is visible at the bottom left of the display}
- Press {button}
- Observe {what has changed}
- Confirm {something has happened}
| 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. |
There was a problem hiding this comment.
suggestion: This example provides a concise step (which is good). The follow on background information is following on the same line. (Might be a formatting issue). Would likely be better to include this in a callout box with a bullet list of tips. (In markdown, use > char). It should also include the "information" icon.
|
|
||
| Create pull request | ||
|
|
||
| 1. 2. To create a pull request, do the following: |
There was a problem hiding this comment.
issue: Check how this is rendered. It comes out as 1. ii. where I expect we were going for 2.
|
|
||
| 1. 2. To create a pull request, do the following: | ||
|
|
||
| a. Navigate to the main page of your repository. |
There was a problem hiding this comment.
suggestion: Suggest all steps should follow unique numbering all through the doc, such as:
- xx
- xx
2.1 xx - xx
|
|
||
| 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" |
There was a problem hiding this comment.
| 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" | |
| 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"``` |
suggestion: suggest additionally address numbering, as per prior comment.
Template quality checklist
This quality checklist will eventually become a pull request template that every contributor needs to add to pull requests against the
templatesrepository.Pull request summary
This pull request is for the new how-to template and guide.
Worked on by: The How-to Working group. Mentor: @gayathri-krishnaswamy
Template contributor checklist
IMPORTANT: The next three sections in this checklist should be filled out by the template contributor at the time they submit this request.
NOTE: Pull requests can only be merged when all boxes are checked.
Which issue does this pull request fix or reference?
This pull request:
Procedural requirements
Template set requirements
Template pull request reviewer checklist
IMPORTANT: The rest of the sections in this checklist should only be filled out by authorized Good Docs Project pull request reviewers. If you are the individual template contributor, do not fill out the rest of the fields or check the boxes.
NOTE: Pull requests can only be merged when all boxes are checked.
Mechanics and formatting requirements - PULL REQUEST REVIEWER ONLY
Overall usability - PULL REQUEST REVIEWER ONLY
Template file requirements - PULL REQUEST REVIEWER ONLY
Template guide requirements - PULL REQUEST REVIEWER ONLY
Deep dive requirements (optional) - PULL REQUEST REVIEWER ONLY
Template example requirements (optional) - PULL REQUEST REVIEWER ONLY