Skip to content

Commit 51199d5

Browse files
Add guideline about "reviewing doc changes"
1 parent ee4bc6f commit 51199d5

File tree

3 files changed

+21
-0
lines changed

3 files changed

+21
-0
lines changed

src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@
4949
- [doc alias policy](./documentation/doc-alias-policy.md)
5050
- [safety comments policy](./documentation/safety-comments.md)
5151
- [how to write documentation](./how-to-write-documentation.md)
52+
- [reviewing doc changes](./reviewing-doc-changes.md)
5253

5354
---
5455

+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)