Skip to content

Commit acdd300

Browse files
Add guideline about "reviewing doc changes"
1 parent b1312b3 commit acdd300

File tree

2 files changed

+20
-0
lines changed

2 files changed

+20
-0
lines changed
+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Reviewing doc changes
2+
3+
Most of the time, it is mostly reviewing that the documentation isn't wrong
4+
in any way and that it follows the
5+
[how to write documentation](./how-to-write-documentation.md) guideline.
6+
7+
There is however something where we need to be extra careful: stability
8+
guarantees.
9+
10+
## Stability guarantees
11+
12+
First, short explanation about what a stability guarantee is: a statement in
13+
the document which explains what the item is doing in a precise case. For
14+
example:
15+
* Showing precisely how a function on floats handles `NaN`.
16+
* Saying that a sort method has a particular running-time bound.
17+
18+
So if a doc change updates/adds/removes a stability guarantee, it has to be
19+
**very** carefully handled!

src/documentation/summary.md

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
- [doc alias policy](./doc-alias-policy.md)
22
- [safety comments policy](./safety-comments.md)
33
- [how to write documentation](./how-to-write-documentation.md)
4+
- [reviewing doc changes](./reviewing-doc-changes.md)

0 commit comments

Comments
 (0)