Skip to content

Commit 494809c

Browse files
supergranularCopilotmyarbsubatoiCopilot
authored
WIP look at replacing "procedural" with "how-to" (#59790)
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Melanie Yarbrough <11952755+myarb@users.noreply.github.com> Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent dc2471b commit 494809c

File tree

3 files changed

+49
-40
lines changed

3 files changed

+49
-40
lines changed
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: How-to content type
3+
intro: Explain how to complete a task using {% data variables.product.github %} products and features.
4+
versions:
5+
fpt: '*'
6+
ghec: '*'
7+
ghes: '*'
8+
category:
9+
- Follow the style guide and content model
10+
allowTitleToDifferFromFilename: true
11+
redirect_from:
12+
- /contributing/style-guide-and-content-model/procedural-content-type
13+
---
14+
15+
How-tos contain numbered steps that describe how to use {% data variables.product.prodname_dotcom %} products to accomplish a task. Generally, they are necessary to get the most from using {% data variables.product.prodname_dotcom %}.
16+
17+
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.
18+
19+
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.
20+
21+
Troubleshooting is its own content type, but how-to articles can include short troubleshooting sections where this helps people complete the task.
22+
23+
## Titles for how-to articles
24+
25+
How-to article titles and sections within articles are task-based and begin with a gerund.
26+
* Use: "Applying for a student developer pack"
27+
Use active and specific verbs (brainstorm or use a thesaurus when needed).
28+
Titles specifically describe the task contained within the article or header, but are general enough to reflect all of the content.
29+
30+
How-to article short titles use short, non-gerund verb phrases. Short titles appear in the sidebar navigation.
31+
* Use: “Manage your plan” or “Create issues with Copilot”
32+
33+
## How-to considerations
34+
35+
For the how-to content template, see [AUTOTITLE](/contributing/writing-for-github-docs/templates#procedural-article-template).
36+
37+
* Follow the style guidelines for procedural steps in [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#procedural-steps).
38+
* How-to content can get repetitive––look for opportunities to group related content into a single longer article.
39+
* Group multiple related how-tos into a single article unless there's a compelling reason not to.
40+
* If disabling a setting or undoing a task requires the same steps and has no special implications, do not write a separate how-to.
41+
* 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.
42+
* Always include the intended outcome of the how-to (generally this will be the title).
43+
* Include troubleshooting tips in known pain points.
44+
45+
## Examples of how-to content
46+
47+
{% ifversion fpt or ghec %}* [AUTOTITLE](/copilot/how-tos/provide-context/use-copilot-spaces/create-copilot-spaces){% endif %}
48+
* [AUTOTITLE](/actions/using-workflows/using-starter-workflows)

content/contributing/style-guide-and-content-model/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ children:
1111
- /contents-of-a-github-docs-article
1212
- /conceptual-content-type
1313
- /referential-content-type
14-
- /procedural-content-type
14+
- /how-to-content-type
1515
- /troubleshooting-content-type
1616
- /release-note-content-type
1717
- /quickstart-content-type

content/contributing/style-guide-and-content-model/procedural-content-type.md

Lines changed: 0 additions & 39 deletions
This file was deleted.

0 commit comments

Comments
 (0)