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
{{ message }}
This repository was archived by the owner on Mar 25, 2018. It is now read-only.
Copy file name to clipboardExpand all lines: GUIDE.md
+69-39Lines changed: 69 additions & 39 deletions
Original file line number
Diff line number
Diff line change
@@ -2,15 +2,17 @@
2
2
3
3
Welcome to the Node.js documentation guide – or more colloquially, the docs on
4
4
docs. If you're here, you're likely looking for guidance on how to write
5
-
documentation for the project. You're in luck! This is where we house all
6
-
of that information.
5
+
documentation for the project. You're in luck! This is where we house all of
6
+
that information.
7
7
8
8
This guide is divided into **why** we're writing docs, **what** we want to
9
9
write, and **how** we write it.
10
10
11
11
* If you're new here, start from the top and go down.
12
-
* If you're ready to write some docs, but don't know what to write, look at the second section.
13
-
* If you're having trouble with formatting, or have a grammar question, look at the last section.
12
+
* If you're ready to write some docs, but don't know what to write, look at the
13
+
second section.
14
+
* If you're having trouble with formatting, or have a grammar question, look at
15
+
the last section.
14
16
15
17
## Why We Write Docs
16
18
@@ -32,7 +34,8 @@ writing for a different platform which might not be nearly [as fun][].
32
34
33
35
To summarize:
34
36
35
-
* Our audiences are **diverse** and have **different goals** coming into the docs.
37
+
* Our audiences are **diverse** and have **different goals** coming into the
38
+
docs.
36
39
* We write docs so that we our audiences can have a **positive experience** with
37
40
Node.
38
41
* We want them to have a positive experience with Node out of **empathy** and
@@ -48,12 +51,15 @@ interleaved in other documentation, which is hugely confusing!
48
51
49
52
For that reason, we split our writing into three categories:
50
53
51
-
1. Guides – documents written to guide a reader through a process, in order to help them learn a concept in service of their larger goal.
52
-
2. Topic – documents written to explain a concept, in order to help the reader make a decision.
53
-
3. Reference – documents written to inform or remind a user of a capability, in order to help the user achieve their goal.
54
+
1. Guides – documents written to guide a reader through a process, in order to
55
+
help them learn a concept in service of their larger goal.
56
+
2. Topic – documents written to explain a concept, in order to help the reader
57
+
make a decision.
58
+
3. Reference – documents written to inform or remind a user of a capability, in
59
+
order to help the user achieve their goal.
54
60
55
-
The larger structure of the project reflects this – there is a `guides` directory,
56
-
a `topics` directory, and a `reference` directory.
61
+
The larger structure of the project reflects this – there is a `guides`
62
+
directory, a `topics` directory, and a `reference` directory.
57
63
58
64
// our directory structure:
59
65
src/
@@ -65,18 +71,19 @@ Every document we author should address **one primary audience** and describe
65
71
**one complete idea**. If a document starts to address two audiences or ideas,
66
72
it can quickly become confusing and hard to maintain. Documents that start to
67
73
transform in this way should be **split up**. When a document about a topic
68
-
starts to describe two ideas, the core concept of both should become a directory
69
-
that documents for both ideas are put into. For example:
74
+
starts to describe two ideas, the core concept of both should become a
75
+
directory that documents for both ideas are put into. For example:
70
76
71
77
topics/streams.md ->
72
78
topics/streams/using-a-stream.md # for users of streams
73
79
topics/streams/writing-a-stream.md # for authors of streams
74
80
topics/streams/index.md # links to both of the above
75
81
76
82
In other cases, reference documentation may have need of describing a topic in
77
-
order to explain an API. In that case, the topic should be described separately,
78
-
as a document in `topics/`, and linked to from the reference in `references/`. This
79
-
is especially true when multiple references need to describe the same topic!
83
+
order to explain an API. In that case, the topic should be described
84
+
separately, as a document in `topics/`, and linked to from the reference in
85
+
`references/`. This is especially true when multiple references need to
86
+
describe the same topic!
80
87
81
88
We believe good documentation is fractal. Guides, topics, and reference may all
82
89
repeat that organization internally, so long as it does not interfere with the
@@ -88,42 +95,65 @@ documentation, but it is not so great to include a full program there.
88
95
89
96
To summarize:
90
97
91
-
* Structure is of paramount important.
92
-
* Decide on an **audience** and an **idea** you want to convey to that audience.
98
+
* Structure is of paramount importance.
99
+
* Decide on an **audience** and an **idea** you want to convey to that
100
+
audience.
93
101
* If the reader is to follow a process to get to a goal, it's a **guide.**
94
-
* If what you're writing conveys a concept to help the reader in decision making, it's a **topic.**
95
-
* When the reader is consulting your document to find a specific piece of information, it's **reference.**
96
-
* Each document should clearly convey *one* idea to *one* audience. All strategies are in service of that goal.
102
+
* If what you're writing conveys a concept to help the reader in decision
103
+
making, it's a **topic.**
104
+
* When the reader is consulting your document to find a specific piece of
105
+
information, it's **reference.**
106
+
* Each document should clearly convey *one* idea to *one* audience. All
107
+
strategies are in service of that goal.
97
108
98
109
## How We Write
99
110
100
111
* Documents are written in markdown files.
101
-
* Those files should be written in `lowercase-with-dashes.md`.
102
-
* Underscores in filenames are allowed only when they are present in the topic the document will describe (e.g., `child_process`.)
103
-
* Older files may use the `.markdown` extension. These may be ported to `.md` at will.
112
+
* Those files should be written in **`lowercase-with-dashes.md`.**
113
+
* Underscores in filenames are allowed only when they are present in the
114
+
topic the document will describe (e.g., `child_process`.)
115
+
* Filenames should be **lowercase**.
116
+
* Older files may use the `.markdown` extension. These may be ported to `.md`
117
+
at will. **Prefer `.md` for all new documents.**
104
118
* Documents should be word-wrapped at 80 characters.
119
+
* Documents should not contain trailing whitespace.
105
120
* Mechanical issues, like spelling and grammar, should be identified by tools,
106
-
insofar as is possible. If not caught by a tool, they should be pointed out by
107
-
human reviewers.
108
-
* The [Oxford comma][] is preferred.
109
-
* Generally avoid personal pronouns in documentation ("I", "you", "we".)
110
-
* Place end-of-sentence punctuation inside wrapping elements – periods go inside parentheses and quotes, not after.
111
-
* Documents must start with a level-one heading. An example document will be linked here eventually.
112
-
* Prefer affixing links to inlining links – prefer `[a link][]` to `[a link](google dot com)`.
113
-
* When documenting APIs, attempt to note the version the API was introduced at the end of the section. If an API has been deprecated, also note the first version that the API appeared deprecated in.
121
+
insofar as is possible. If not caught by a tool, they should be pointed out by
122
+
human reviewers.
123
+
* US spelling is preferred. "Capitalize" vs. "Capitalise", "color" vs.
124
+
"colour", etc.
125
+
* Though controversial, the [Oxford comma][] is preferred for clarity's sake.
126
+
* Generally avoid personal pronouns in reference documentation ("I", "you",
127
+
"we".)
128
+
* Pronouns are acceptable in more colloquial documentation, like guides.
129
+
* Place end-of-sentence punctuation inside wrapping elements – periods go
130
+
inside parentheses and quotes, not after.
131
+
* Documents must start with a level-one heading. An example document will be
132
+
linked here eventually.
133
+
* Prefer affixing links to inlining links – prefer `[a link][]` to
134
+
`[a link](google dot com)`.
135
+
* When documenting APIs, note the version the API was introduced at
136
+
the end of the section. If an API has been deprecated, also note the first
137
+
version that the API appeared deprecated in.
138
+
139
+
### Tone
114
140
115
141
The tone of your writing should change in service of the goal of the document.
116
142
For example, *guides* may be warm and whimsical in order to make the reader
117
-
comfortable and pique their interest. *Reference material* should adopt a terser,
118
-
more clinical tone, in order to more efficiently convey information to the reader.
119
-
*Topics* are halfway between the two – a more neutral tone may be adopted, but it's
120
-
okay to mix some humanity in as well!
143
+
comfortable and pique their interest. *Reference material* should adopt a
144
+
terser, more clinical tone, in order to more efficiently convey information to
145
+
the reader. *Topics* are halfway between the two – a more neutral tone may be
146
+
adopted, but it's okay to mix some humanity in as well!
147
+
148
+
### Introducing Changes
121
149
122
150
To introduce changes, open a PR to this repository. One "LGTM" comment from
123
-
another team member is sufficient to merge a change. When describing your change,
124
-
make sure to note why you are making the change in the description. If you are
125
-
writing a new doc, please include a one-to-three sentence paragraph explaining the
126
-
idea you are attempting to convey and the audience you are targeting.
151
+
another team member is sufficient to merge a change. When describing your
152
+
change, make sure to note why you are making the change in the description. If
153
+
you are writing a new doc, please include a one-to-three sentence paragraph
154
+
explaining the idea you are attempting to convey and the audience you are
155
+
targeting. For more information on this, see [CONTRIBUTING.md][].
0 commit comments