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?