@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
reggi/cache-based-on-version
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
md 117 lines 5.54 KB
Rendered Raw
1 # Content model
2
3 ## Introduction
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.
6
7 For style questions, default to https://github.com/github/docs-internal/blob/main/contributing/content-style-guide.md
8
9 ## Content structure
10
11 Docs are grouped by topic.
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)
16
17 ### Categories
18
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.
20
21 ### Articles
22
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.
24
25 #### Content order
26
27 Introduce content from the broadest applicability to the most specific, following this order:
28
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
36
37 Articles answer, “What is it? Why do it?” and then “How does someone do it?”
38
39 #### Content types
40
41 **Conceptual**
42
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.
44
45 How to write conceptual content
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)
54
55 **Procedural**
56
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.
58
59 How to write procedural content
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
66
67 How to write prerequisites
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
74
75 #### Contents of an article
76
77 - Title
78 - Conceptual content
79 - Prerequisites (if applicable)
80 - Procedural content
81 - Troubleshooting (if applicable)
82
83 ## User and job stories
84
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.
86
87 ### User stories
88
89 Create user stories to better understand each audience when a feature affects more than one audience.
90
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...].
92
93 ### Job stories
94
95 Job stories are narrow, granular, and useful for targeted actions or specific tasks that a single audience wants to achieve.
96
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...].
98
99 ### Acceptance criteria
100
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.
102
103 ## Article template
104
105 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.
106
107 ```
108 ---
109 title:
110 ---
111 import shared from '~/shared.js'
112
113 // Conceptual content: What feature is the article about?
114 // Prerequisites (if applicable): Who can use the feature?
115 // Procedural content: How do you use the feature?
116 // Troubleshooting (if applicable): What do you do if the feature isn't working?
117 ```