1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
class: center, middle
Maintaining documentation: RelEng
=============================================================================
What, who, how, when.
---
Problem
=============================================================================
The problem isn't that we have too little documentation.
The problem is what we have too much, it's hard to find, and some of
it is out of date or otherwise wrong.
---
A proposal
=============================================================================
* We take **ownership**.
* We **write** docs.
* We **maintain** docs.
* We **update** docs.
* We **fix** docs.
* **Together**.
* No question left unanswered by documentation.
---
class: center, middle
It's more important that do documentation exists and answers questions
that are asked than that it is great technical writing. A crappy
document in broken English is better than nothing, as long as it
doesn't mislead the reader.
---
class: left, middle
**Accuracy, brevity, clarity**
Simon Illyan, head of Imperial Security
---
In more detail
=============================================================================
* We **pick** the aspects of what we are responsible for, as a team,
and list the documentation that we or others need.
* We **find or write** the documentation. Much of it probably already
exists.
* We **make a list** of what we take responsibility for: if it's not
on the list, it's not our responsibility.
* We **review** all documentation **regularly**, maybe once a quarter,
in a rotating fashion.
* We make a **checklist** of what makes good documentation for us.
* We make a **process** for dealing with other documentation that
touches our team's scope that we encounter. _Hunt it down and kill
it?_ (Or adopt it, or replace with a link to our own document?)
* We make a **feedback loop** for documentation. When anyone asks
RelEng about anything, we check if the answer is in our
documentation and if not, create a task to improve the
documentation?
|