You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contributing/content-model.md
+15-15Lines changed: 15 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,11 +9,11 @@ _Full TOC :arrow_upper_left:_
9
9
10
10
## Introduction
11
11
12
-
This content model explains the goals of each type of content we create within GitHub Docs, and what to include when you're writing or updating an article. We use a model to ensure that our content consistently, clearly, and comprehensively communicates what our customers need to achieve their goals with GitHub quickly and easily.
12
+
This content model explains the goals of each type of content we create within GitHub Docs, and what to include when you're writing or updating an article. We use a model to ensure that our content consistently, clearly, and comprehensively communicates what people need to achieve their goals with GitHub quickly and easily.
13
13
14
-
We use these types across all documentation sets to provide a consistent user experience––any content type applies to any product or audience. Our content types evolve over time and we add new types as needed. We don't publish content that doesn't follow the model.
14
+
We use these types across all documentation sets to provide a consistent user experience––any content type applies to any product or audience. Our content types evolve over time and we add new types as needed. We only publish content that follows the model.
15
15
16
-
Consistency helps customers form mental models of the documentation and understand how to find the information they need as they return to GitHub Docs over time. It’s also more efficient to maintain and update consistent content, making it easier and quicker to contribute to docs whether you're an open source contributor making your first commit or a GitHub writer documenting an entire new product.
16
+
Consistency helps people form mental models of the documentation and understand how to find the information they need as they return to GitHub Docs over time. It’s also more efficient to maintain and update consistent content, making it easier and quicker to contribute to docs whether you're an open source contributor making your first commit or a GitHub writer documenting an entire new product.
17
17
18
18
## Content structure
19
19
@@ -114,12 +114,12 @@ Topics are used to filter articles and are searchable across the docs site. For
114
114
#### Topics for all content types
115
115
- All articles should have at least one topic
116
116
- Use nouns as topics
117
-
- Topics help customers meaningfully group content
117
+
- Topics help people meaningfully group content
118
118
- When possible, use more specific topics that are relevant and not just broad topics. For example, `REST` or `GraphQL` rather than just `API`
119
119
- Ensure that topics on similar articles are consistent so that people who filter by a topic get all of the relevant articles. For example, all articles about CI should have the `CI` topic plus more specific topics
120
120
- Avoid ambiguous topics. For example, `Actions` may not be a useful topic within the Actions product since it could refer to the product GitHub Actions or the product element called an action
121
121
- Topics add value beyond and do not replicate the article’s title, type, or category
122
-
- For example, within the Actions product, `Actions` does not add value since a customer already knows they are looking at Actions docs
122
+
- For example, within the Actions product, `Actions` does not add value since someone in this section of the docs would already know that they are looking at Actions docs
123
123
- Use `Fundamentals` for articles related to the core concepts of a product area.
124
124
- Use: `Fundamentals` in an article like “Introduction to GitHub Actions”
125
125
- Avoid: `Actions` in an article like "Introduction to GitHub Actions"
@@ -155,7 +155,7 @@ Any of these content types can be shared as an article on its own, and some cont
155
155
156
156
### Conceptual
157
157
158
-
Conceptual content helps customers 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. Conceptual content is clear enough for a novice audience but also includes relevant information for advanced users. Customers most often use conceptual content when they're learning.
158
+
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. Conceptual content is clear enough for a novice audience but also includes relevant information for advanced users. People most often use conceptual content when they're learning.
159
159
160
160
We create conceptual articles and conceptual sections within other articles. Most major products, features, or subjects have their own conceptual article.
161
161
@@ -186,7 +186,7 @@ Use the [conceptual content template](https://github.com/github/docs/blob/main/c
186
186
187
187
### Referential
188
188
189
-
Referential content provides detailed information that customers need while they're actively using a feature.
189
+
Referential content provides detailed information that people need while they're actively using a feature.
190
190
191
191
We create referential articles and referential sections within other articles.
192
192
- Some major subjects may require their own referential article, especially if there is a large amount of referential content, such as for search syntax or YAML syntax in GitHub Actions.
@@ -224,9 +224,9 @@ Use the [referential content template](https://github.com/github/docs/blob/main/
224
224
225
225
### Procedural
226
226
227
-
Procedural content helps customers complete a task from start to finish while they're using GitHub. Procedural content gives context on how the task fits into the customer's larger journey.
227
+
Procedural content helps people complete a task from start to finish while they're using GitHub. Procedural content gives context on how the task fits into someone's larger journey.
228
228
229
-
We create procedural articles and procedural sections within larger articles.
229
+
We create procedural articles and procedural sections within larger articles.
230
230
231
231
#### How to write procedural articles
232
232
Use the [procedural content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#procedural) to write a procedural article.
@@ -253,7 +253,7 @@ Use the [procedural content template](https://github.com/github/docs/blob/main/c
253
253
254
254
### Combining multiple content types
255
255
256
-
Often, it's helpful to group information in context to help customers complete a complex task, understand a set of related tasks, or illustrate an entire workflow. Use longer articles combining content types to ensure the customer finds contextual content in the right place. Longer articles also help eliminate duplication of content and prepare content to scale as more options are added to the product. Customers most often need longer articles while actively using the product, and may need to consult the article at different points on their journey.
256
+
Often, it's helpful to group information in context to help people complete a complex task, understand a set of related tasks, or illustrate an entire workflow. Use longer articles combining content types to ensure people find contextual content in the right place. Longer articles also help eliminate duplication of content and prepare content to scale as more options are added to the product. People most often need longer articles while actively using the product, and they may need to consult the article at different points on their journey.
257
257
258
258
#### How to combine multiple content types in an article
259
259
- Use conceptual, procedural, referential, or troubleshooting content in a longer article, and do not use quickstart or tutorials
@@ -278,7 +278,7 @@ Often, it's helpful to group information in context to help customers complete a
278
278
279
279
Quickstarts enable a user to quickly complete a discrete, focused task by illustrating a workflow with only essential steps, in about five minutes or 600 words. Quickstarts can be used for quickly getting set up with a new tool, or for quickly completing another task. For more complex tasks, use a tutorial.
280
280
281
-
Quickstarts are useful when the customer already understands the feature or product and is ready to try it out. Users of quickstarts are not looking for an explanation and don't need to be convinced to use the product––they just want instructions quickly. Users who don't understand a step are willing to dig deeper in a separate doc.
281
+
Quickstarts are useful when someone already understands the feature or product and is ready to try it out. Users of quickstarts are not looking for an explanation and don't need to be convinced to use the product––they just want instructions quickly. Users who don't understand a step are willing to dig deeper in a separate doc.
282
282
283
283
#### How to write a quickstart
284
284
Use the [quickstart template](https://github.com/github/docs/blob/main/contributing/content-templates.md#quickstart) to create a quickstart guide.
@@ -313,9 +313,9 @@ Contents of quickstarts:
313
313
314
314
### Tutorial
315
315
316
-
Tutorials help customers learn about products and solve real world problems by guiding them through the entire workflow to complete a task. Tutorials are more conversational in tone than other content. A tutorial feels like a developer-to-developer conversation while remaining accessible to readers with varied technical knowledge. Products with tutorials must already have a quickstart. For bite-sized workflows, use the quickstart model instead.
316
+
Tutorials help people learn about products and solve real world problems by guiding them through the entire workflow to complete a task. Tutorials are more conversational in tone than other content. A tutorial feels like a developer-to-developer conversation while remaining accessible to readers with varied technical knowledge. Products with tutorials must already have a quickstart. For bite-sized workflows, use the quickstart model instead.
317
317
318
-
Tutorials are useful when the customer has a basic understanding of the product and is interested in extending their understanding to solve a specific problem. Tutorials are for customers who want expert advice and a detailed discussion of best practices related to their problem. Tutorials also help customers who've implemented similar solutions in the past with other products use GitHub. Tutorials can also help customers validate whether the solution is appropriate for their needs.
318
+
Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem. Tutorials are for people who want expert advice and a detailed discussion of best practices related to their problem. Tutorials also help people who've implemented similar solutions in the past with other products use GitHub. Tutorials can also help people validate whether the solution is appropriate for their needs.
319
319
320
320
#### How to write a tutorial
321
321
Use the [tutorial template](https://github.com/github/docs/blob/main/contributing/content-templates.md#tutorial) to create a tutorial.
@@ -423,7 +423,7 @@ Check the source files and `gated-features` to see how source content is written
423
423
424
424
### Permissions statements
425
425
426
-
Every procedure includes a permissions statement explaining the role required to take the action described in the procedure, helping customers understand whether they'll be able to complete the task.
426
+
Every procedure includes a permissions statement explaining the role required to take the action described in the procedure, which helps people understand whether they'll be able to complete the task.
427
427
428
428
Occasionally, it's relevant to mention required permissions in conceptual content, especially in standalone conceptual articles. Make sure to also include a permissions statement in related procedures (or write a longer article combining all of the content).
429
429
@@ -446,7 +446,7 @@ Tables of contents are automatically generated. For more information see "[Autog
446
446
447
447
### Prerequisites
448
448
449
-
Prerequisites are information that customers need to know before proceeding with a procedure, so that they can prepare everything they need before starting the task.
449
+
Prerequisites are information that people need to know before proceeding with a procedure, so that they can prepare everything they need before starting the task.
450
450
451
451
#### How to write prerequisites
452
452
- Write prerequisites immediately before a procedure's numbered steps.
0 commit comments