|
1 | 1 | # Content model |
| 2 | + |
2 | 3 | ## Introduction |
3 | | -This content model explains the goals of content in the npm 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 npm. |
4 | | -Following a content model creates consistency that helps users and maintainers of the docs. |
| 4 | + |
| 5 | +This content model explains the goals of content in the npm 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 npm. Following a content model creates consistency that helps users and maintainers of the docs. |
5 | 6 |
|
6 | 7 | For style questions, default to https://github.com/github/docs-internal/blob/main/contributing/content-style-guide.md |
7 | 8 |
|
8 | 9 | ## Content structure |
| 10 | + |
9 | 11 | Docs are grouped by topic. |
10 | | -* Top-level doc set (Example: https://docs.npmjs.com/packages-and-modules) |
11 | | - * Categories (Example: https://docs.npmjs.com/packages-and-modules/introduction-to-packages-and-modules) |
12 | | - * Articles (Example: https://docs.npmjs.com/about-packages-and-modules) |
| 12 | + |
| 13 | +- Top-level doc set (Example: https://docs.npmjs.com/packages-and-modules) |
| 14 | + - Categories (Example: https://docs.npmjs.com/packages-and-modules/introduction-to-packages-and-modules) |
| 15 | + - Articles (Example: https://docs.npmjs.com/about-packages-and-modules) |
13 | 16 |
|
14 | 17 | ### Categories |
| 18 | + |
15 | 19 | Categories are organized around a feature or a discrete set of tasks. Use titles that are task-based and describe the purpose or goal of the category. |
16 | 20 |
|
17 | 21 | ### Articles |
| 22 | + |
18 | 23 | Articles are the basic unit of content for the docs. Use titles that are clear, descriptive, and specific, with the same terminology as the product itself. All articles follow the same content order. |
19 | 24 |
|
20 | 25 | #### Content order |
| 26 | + |
21 | 27 | Introduce content from the broadest applicability to the most specific, following this order: |
22 | 28 |
|
23 | | -* Conceptual content |
24 | | -* Procedural content for enabling a feature or setting |
25 | | -* Procedural content on using a feature |
26 | | -* Procedural content on managing a feature or setting |
27 | | -* Procedural content on disabling a feature or setting |
28 | | -* Procedural content on destructive actions (e.g. deletion) |
29 | | -* Troubleshooting information |
| 29 | +- Conceptual content |
| 30 | +- Procedural content for enabling a feature or setting |
| 31 | +- Procedural content on using a feature |
| 32 | +- Procedural content on managing a feature or setting |
| 33 | +- Procedural content on disabling a feature or setting |
| 34 | +- Procedural content on destructive actions (e.g. deletion) |
| 35 | +- Troubleshooting information |
30 | 36 |
|
31 | 37 | Articles answer, “What is it? Why do it?” and then “How does someone do it?” |
32 | 38 |
|
33 | 39 | #### Content types |
34 | 40 |
|
35 | 41 | **Conceptual** |
36 | 42 |
|
37 | | -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. |
38 | | -If people need certain permissions to do a task described in the article, include a permissions statement describing who can do the task in the conceptual information. |
| 43 | +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. If people need certain permissions to do a task described in the article, include a permissions statement describing who can do the task in the conceptual information. |
39 | 44 |
|
40 | 45 | How to write conceptual content |
41 | | -* If people need specific permissions to do what is described in the article, list those required permissions |
42 | | -* Describe in plain language what the feature, setting, or topic is |
43 | | -* Describe its purpose and why it’s useful to the reader |
44 | | -* Share use cases or examples |
45 | | -* If relevant, describe how the feature or topic works |
46 | | -* Highlight any details the reader needs to know to use the feature |
47 | | -* Include next steps for getting started with the feature (whether through further reading links or content within the article itself) |
| 46 | + |
| 47 | +- If people need specific permissions to do what is described in the article, list those required permissions |
| 48 | +- Describe in plain language what the feature, setting, or topic is |
| 49 | +- Describe its purpose and why it’s useful to the reader |
| 50 | +- Share use cases or examples |
| 51 | +- If relevant, describe how the feature or topic works |
| 52 | +- Highlight any details the reader needs to know to use the feature |
| 53 | +- Include next steps for getting started with the feature (whether through further reading links or content within the article itself) |
48 | 54 |
|
49 | 55 | **Procedural** |
50 | 56 |
|
51 | 57 | Procedural content helps people complete a task from start to finish while they're using npm. Procedural content gives context on how the task fits into someone's larger journey. If a procedure has prerequisites, include them before the procedural content. |
52 | 58 |
|
53 | 59 | How to write procedural content |
54 | | -* Group multiple related procedures into a single article unless there's a reason not to |
55 | | -* Use ordered lists for procedural steps |
56 | | -* If a step is optional, indicate that first |
57 | | -* Tell readers the expected outcome of any procedures |
58 | | -* Include troubleshooting tips as frequently as possible |
| 60 | + |
| 61 | +- Group multiple related procedures into a single article unless there's a reason not to |
| 62 | +- Use ordered lists for procedural steps |
| 63 | +- If a step is optional, indicate that first |
| 64 | +- Tell readers the expected outcome of any procedures |
| 65 | +- Include troubleshooting tips as frequently as possible |
59 | 66 |
|
60 | 67 | How to write prerequisites |
61 | | -* Put the prerequisites immediately before the procedure that they are relevant to. If the prerequisites are relevant to all the procedures in an article, put them after the conceptual content and before the first procedure |
62 | | -* You can use a list, a sentence, or a paragraph to explain prerequisites |
63 | | -* You can also use a separate prerequisites section when: |
64 | | - * The prerequisite information is very important and should not be missed |
65 | | - * There is more than one prerequisite |
| 68 | + |
| 69 | +- Put the prerequisites immediately before the procedure that they are relevant to. If the prerequisites are relevant to all the procedures in an article, put them after the conceptual content and before the first procedure |
| 70 | +- You can use a list, a sentence, or a paragraph to explain prerequisites |
| 71 | +- You can also use a separate prerequisites section when: |
| 72 | + - The prerequisite information is very important and should not be missed |
| 73 | + - There is more than one prerequisite |
66 | 74 |
|
67 | 75 | #### Contents of an article |
68 | | -* Title |
69 | | -* Conceptual content |
70 | | -* Prerequisites (if applicable) |
71 | | -* Procedural content |
72 | | -* Troubleshooting (if applicable) |
| 76 | + |
| 77 | +- Title |
| 78 | +- Conceptual content |
| 79 | +- Prerequisites (if applicable) |
| 80 | +- Procedural content |
| 81 | +- Troubleshooting (if applicable) |
73 | 82 |
|
74 | 83 | ## User and job stories |
| 84 | + |
75 | 85 | When planning content, you can create user and job stories to define acceptance criteria that help determine if an article is helping users accomplish their goals. |
76 | 86 |
|
77 | 87 | ### User stories |
| 88 | + |
78 | 89 | Create user stories to better understand each audience when a feature affects more than one audience. |
79 | 90 |
|
80 | 91 | As a [person in a particular role], I want to [perform an action or find something out], so that I can [achieve my goal of...]. |
81 | 92 |
|
82 | 93 | ### Job stories |
| 94 | + |
83 | 95 | Job stories are narrow, granular, and useful for targeted actions or specific tasks that a single audience wants to achieve. |
84 | 96 |
|
85 | 97 | When [there's a particular situation], I want to [perform an action or find something out], so that I can [achieve my goal of...]. |
86 | 98 |
|
87 | 99 | ### Acceptance criteria |
| 100 | + |
88 | 101 | Acceptance criteria explain the specific ways we'll know when a user or job story is considered complete. To define acceptance criteria, identify what an article has to offer someone for them to complete their desired task and feel satisfied. |
89 | 102 |
|
90 | 103 | ## Article template |
|
0 commit comments