How-tos contain numbered steps that describe how to use GitHub products to accomplish a task. Generally, they are necessary to get the most from using GitHub.
How-to articles focus on the minimum essential steps for completing a task. They may link to other content types as prerequisites (especially concepts or reference) or next steps (especially tutorials). In keeping with our linking strategy, these should be used only when explicitly useful and necessary.
Generally including 1-2 brief introductory sentences before the steps is fine. If more explanation beyond a couple of sentences is needed, consider adding the information instead as a conceptual article.
Troubleshooting is its own content type, but how-to articles can include short troubleshooting sections where this helps people complete the task.
Titles for how-to articles
How-to article titles and sections within articles are task-based and begin with a gerund.
- Use: "Applying for a student developer pack" Use active and specific verbs (brainstorm or use a thesaurus when needed). Titles specifically describe the task contained within the article or header, but are general enough to reflect all of the content.
How-to article short titles use short, non-gerund verb phrases. Short titles appear in the sidebar navigation.
- Use: “Manage your plan” or “Create issues with Copilot”
How-to considerations
For the how-to content template, see Templates.
- Follow the style guidelines for procedural steps in Style guide.
- How-to content can get repetitive––look for opportunities to group related content into a single longer article.
- Group multiple related how-tos into a single article unless there's a compelling reason not to.
- If disabling a setting or undoing a task requires the same steps and has no special implications, do not write a separate how-to.
- If disabling a setting or undoing a task requires different steps or has important or special implications, create a longer article to contain both how-tos.
- Always include the intended outcome of the how-to (generally this will be the title).
- Include troubleshooting tips in known pain points.