Here is my proposal for any sort of docs that don't live right alongside the code. I have yet to put this into practice.
There are 4 states for any page:
- Maintained: "We are maintain this and aim to keep up to date. Message #slack-channel with any questions."
- Stale: "Oops... we didn't."
- News: "This represents our current thinking as of 23-Mar-2020"
- Record: "This is a historical record of our intended system design, produced on 4-Aug-2018."
When you write docs, be very clear whether you are writing a new report or something you intend to maintain. Reports become historical records after 1-3 months. Default to a report.
Why? To keep small the number of docs which are "Maintained". Every maintained page is owned by a team of 2-10 people and the channel to contact them is visible on the page. Ideally, there would be a tool which attaches to every "Maintained" page and does 3 things.
1) Let the reader mark it as possibly stale or ask a question, then messages the page owners about that. Marks the page as stale within a week of non-response.
2) Mark the page as stale if the text isn't updated at least every 3 months.
3) Mark the page as stale if it doesn't get at least N page-views in 3 months.
I'm serious about point #3. If a page is rarely-read by others, then the team which owns it is not pointing people to it or using it for training. If that is the case, then why should they spend time and attention to keep it up-to-date?
Is it an emergency runbook? Well then either that info is important enough to walk through it periodically, or you should be honest with yourself that what that doc really says is, "This was the suggested runbook we came up with after a post-mortem 2 years ago. It might be very useful for understanding the system. Maybe it even still works."
This would make a great plugin for something like Confluence. Most places I’ve worked, the wiki was where information went to die. It’d be nice if the unused/outdated stuff could fade away automatically-ish.
There are 4 states for any page:
- Maintained: "We are maintain this and aim to keep up to date. Message #slack-channel with any questions."
- Stale: "Oops... we didn't."
- News: "This represents our current thinking as of 23-Mar-2020"
- Record: "This is a historical record of our intended system design, produced on 4-Aug-2018."
When you write docs, be very clear whether you are writing a new report or something you intend to maintain. Reports become historical records after 1-3 months. Default to a report.
Why? To keep small the number of docs which are "Maintained". Every maintained page is owned by a team of 2-10 people and the channel to contact them is visible on the page. Ideally, there would be a tool which attaches to every "Maintained" page and does 3 things.
1) Let the reader mark it as possibly stale or ask a question, then messages the page owners about that. Marks the page as stale within a week of non-response.
2) Mark the page as stale if the text isn't updated at least every 3 months.
3) Mark the page as stale if it doesn't get at least N page-views in 3 months.
I'm serious about point #3. If a page is rarely-read by others, then the team which owns it is not pointing people to it or using it for training. If that is the case, then why should they spend time and attention to keep it up-to-date?
Is it an emergency runbook? Well then either that info is important enough to walk through it periodically, or you should be honest with yourself that what that doc really says is, "This was the suggested runbook we came up with after a post-mortem 2 years ago. It might be very useful for understanding the system. Maybe it even still works."