|
1 | 1 | --- |
2 | | -title: Conceptual content type |
| 2 | +title: Concepts content type |
3 | 3 | intro: People most often use conceptual content when they are learning about something new to them. |
| 4 | +category: |
| 5 | + - Follow the style guide and content model |
4 | 6 | versions: |
5 | 7 | fpt: '*' |
6 | 8 | ghec: '*' |
7 | 9 | ghes: '*' |
8 | | -category: |
9 | | - - Follow the style guide and content model |
| 10 | +redirect_from: |
| 11 | + - /contributing/style-guide-and-content-model/conceptual-content-type |
10 | 12 | --- |
11 | 13 |
|
12 | 14 | Conceptual content helps people understand a feature or topic by providing a clear, high-level overview, explanation of how the feature or topic can help them on their journey, and context like use cases or examples. |
13 | 15 |
|
14 | | -We create conceptual articles and conceptual sections within other articles. Most major products, features, or subjects have their own conceptual article. |
| 16 | +We create concepts articles and conceptual sections within other articles. Most major products, features, or subjects have their own concepts article. |
| 17 | + |
| 18 | +## Deciding between an article or a section |
| 19 | + |
| 20 | +How-tos or tutorials can have 1-2 brief introductory sentences before the steps. If more explanation beyond a couple of sentences is needed, that’s when we should consider whether it merits a spot in a concepts article. |
| 21 | + |
| 22 | +However, we should be selective. Not every concept or “About X” section needs its own article. Generally this comes down to how much information will be useful to the user that we need to include. |
15 | 23 |
|
16 | 24 | ## How to write conceptual content |
17 | 25 |
|
18 | | -For the conceptual content template, see [AUTOTITLE](/contributing/writing-for-github-docs/templates#conceptual-article-template). |
| 26 | +For the conceptual content template, see [AUTOTITLE](/contributing/writing-for-github-docs/templates#concepts-article-template). |
19 | 27 |
|
20 | 28 | * Describe in plain language what the feature, product, or topic is. |
21 | 29 | * Describe its purpose and why it’s useful to the reader. |
22 | 30 | * Share use cases or examples. |
23 | | -* If relevant, describe how the feature or topic works (be mindful of audience and the right location for deep dives into technical details). |
24 | | -* Highlight any details the reader needs to know to use the feature. |
25 | | -* Include next steps for getting started with the feature (whether through further reading links or content within the article itself). |
26 | 31 |
|
27 | 32 | ## Titles for conceptual content |
28 | 33 |
|
29 | | -* Conceptual articles or headers of conceptual sections start with "About [subject]”. |
| 34 | +Short titles for articles should be one word or a noun phrase. If the articles appear under Concepts in the sidebar avoid using "About", unless the article appears under a heading of the same name. Ex: "Coding agent" and "About coding agent". |
| 35 | + |
| 36 | +Headers of conceptual sections in articles start with "About [subject]”. |
30 | 37 | * Use a noun to describe the subject. |
31 | 38 | * Use: "About {% data variables.product.prodname_code_scanning %}" |
32 | 39 | * Avoid: "About scanning your code for vulnerabilities" |
|
0 commit comments