Create CONTENT-MODEL.md
Ethan Palm committed
Sep 23, 2022 at 15:15 UTC
28dac64b619bc8886e3cefcf161e6d9602f2d30f
1 file changed
+104
CONTENT-MODEL.md
new
+104
@@ -0,0 +1,104 @@
1
+# Content model
2
+## 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.
5
+
6
+For style questions, default to https://github.com/github/docs-internal/blob/main/contributing/content-style-guide.md
7
+
8
+## Content structure
9
+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)
13
+
14
+### Categories
15
+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
+
17
+### Articles
18
+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
+
20
+#### Content order
21
+Introduce content from the broadest applicability to the most specific, following this order:
22
+
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
30
+
31
+Articles answer, “What is it? Why do it?” and then “How does someone do it?”
32
+
33
+#### Content types
34
+
35
+**Conceptual**
36
+
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.
39
+
40
+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)
48
+
49
+**Procedural**
50
+
51
+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
+
53
+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
59
+
60
+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
66
+
67
+#### Contents of an article
68
+* Title
69
+* Conceptual content
70
+* Prerequisites (if applicable)
71
+* Procedural content
72
+* Troubleshooting (if applicable)
73
+
74
+## User and job stories
75
+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
+
77
+### User stories
78
+Create user stories to better understand each audience when a feature affects more than one audience.
79
+
80
+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
+
82
+### Job stories
83
+Job stories are narrow, granular, and useful for targeted actions or specific tasks that a single audience wants to achieve.
84
+
85
+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
+
87
+### Acceptance criteria
88
+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
+
90
+## Article template
91
+
92
+You can use this template when starting a new article. For more information about importing shared data to an article, see the [`CONTRIBUTING`](https://github.com/npm/documentation/blob/main/CONTRIBUTING.md#shared-content) file.
93
+
94
+```
95
+---
96
+title:
97
+---
98
+import shared form '../../../src/shared.js'
99
+
100
+// Conceptual content: What feature is the article about?
101
+// Prerequisites (if applicable): Who can use the feature?
102
+// Procedural content: How do you use the feature?
103
+// Troubleshooting (if applicable): What do you do if the feature isn't working?
104
+```