From 5e29d53d1cf83168b7e82e7c12b28c8721aeb2a6 Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <lwirzenius@wikimedia.org>
Date: Mon, 22 Apr 2019 08:30:06 -0500
Subject: Add: pgptalk, docmaint

---
 docmaint.mdwn | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docmaint.mdwn

(limited to 'docmaint.mdwn')

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?
-- 
cgit v1.2.1