diff options
author | Lars Wirzenius <lwirzenius@wikimedia.org> | 2019-04-22 08:30:06 -0500 |
---|---|---|
committer | Lars Wirzenius <lwirzenius@wikimedia.org> | 2019-04-22 08:30:06 -0500 |
commit | 5e29d53d1cf83168b7e82e7c12b28c8721aeb2a6 (patch) | |
tree | 8b673ce5e189b87931e676b542e2b601b76fbb96 /docmaint.mdwn | |
download | wmf-talks-5e29d53d1cf83168b7e82e7c12b28c8721aeb2a6.tar.gz |
Add: pgptalk, docmaint
Diffstat (limited to 'docmaint.mdwn')
-rw-r--r-- | docmaint.mdwn | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/docmaint.mdwn b/docmaint.mdwn new file mode 100644 index 0000000..560138b --- /dev/null +++ b/docmaint.mdwn @@ -0,0 +1,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? |