3 ms·

For me, the biggest source of friction when I sit down to write documentation is the knowledge that what I write will eventually wind up out of date and mislead

For me, the biggest source of friction when I sit down to write documentation is the knowledge that what I write will eventually wind up out of date and misleading - which can be worse than missing. What processes or tools do you know of to keep documentation up to date as code and environment change underneath it?

njharman 7y ago
Keeping docs and code as close together as possible. Certainly same repo. But for instance one of pythons greatest feature is docstrings. Which has encouraged documentation in the code. Other than that document in comments. And things like openapi and sphinx to generate docs from code. Low level docs such as foo() does x and raises error when y should be expressed as unit tests. External to code docs should be limited to things like deployment process.design docs (part of point of which is their history should be versioned not changed.
- dllthomas 7y ago
  Proximity is a big help, for sure. Cross-references, ideally checked mechanically, can be helpful in making things proximate to multiple points. I very much agree with expressing assertions as tests. Doctest is an interesting point in the space, here. An idea I've had (and prototyped, but never quite got where I wanted) is a system where I can add references to tests as citations supporting claims in documentation, such that when the test fails the assertions it supports can be surfaced. Also, documentation that is frequently used is typically thereby checked against reality, and necessary updates found quickly. But much documentation won't be sufficiently frequently used to rely on that. There are many things that help. I'm always looking for more. Thanks for your input :)
afarrell 7y ago
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."
- dllthomas 7y ago
  Very interesting proposal.
- dceddia 7y ago
  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.
with-point 7y ago
Shameless self-promotion: That was exact problem I was facing during my entire career. That's why we decided to build a tool which links documentation and code -- https://nots.io https://nots.io This gives at least two benefits: now it's easy to find the right doc straight from the code you're working on. Also Nots tracks updates in code behind each doc, and marks the docs as obsolete if code has drastically changed.

njharman 7y ago

Keeping docs and code as close together as possible. Certainly same repo. But for instance one of pythons greatest feature is docstrings. Which has encouraged documentation in the code. Other than that document in comments. And things like openapi and sphinx to generate docs from code. Low level docs such as foo() does x and raises error when y should be expressed as unit tests. External to code docs should be limited to things like deployment process.design docs (part of point of which is their history should be versioned not changed.

dllthomas 7y ago
Proximity is a big help, for sure. Cross-references, ideally checked mechanically, can be helpful in making things proximate to multiple points. I very much agree with expressing assertions as tests. Doctest is an interesting point in the space, here. An idea I've had (and prototyped, but never quite got where I wanted) is a system where I can add references to tests as citations supporting claims in documentation, such that when the test fails the assertions it supports can be surfaced. Also, documentation that is frequently used is typically thereby checked against reality, and necessary updates found quickly. But much documentation won't be sufficiently frequently used to rely on that. There are many things that help. I'm always looking for more. Thanks for your input :)

afarrell 7y ago

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."

dllthomas 7y ago
Very interesting proposal.
dceddia 7y ago
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.

with-point 7y ago

Shameless self-promotion: That was exact problem I was facing during my entire career. That's why we decided to build a tool which links documentation and code -- https://nots.io https://nots.io This gives at least two benefits: now it's easy to find the right doc straight from the code you're working on. Also Nots tracks updates in code behind each doc, and marks the docs as obsolete if code has drastically changed.