We are in a situation where we have been through quite a few rapid changes while working towards getting things set up in a cloud provider. This rapid-fire change means that a lot of the documentation we had written previously is now out of date. It is the worst kind of documentation, because it now does not reflect reality.
Outdated Documentation
This is how documentation usually comes to us; as outdated. It is no longer relevant. When we approach documentation, this is really how we assume it is. We assume it is now incorrect.
The closer the documentation is to the code itself the lesser this risk is. A Confluence site for example is all but guaranteed to be out of date. A Readme file is going to be fairly close, but some things will have changed. A code comment is probably pretty accurate.
Documentation First
There is an approach to documentation similar to Test Driven Development, Documentation Driven Development. Start with writing the documentation, and then work on the code to flush out that documentation. This is really just another way to get you into the mindset of the consumer, similar to writing the unit tests first. Think about how the clients are going to end up using this bit of code, or this feature. Explain what it should be doing, and then make it do that.
The Behavior Driven Development models flow out of this idea.
Constant Change
We all know that nothing is static; things change constantly. That is why we often assume the documentation is out of date. It is highly likely that if the documentation hasn’t been touched in the last couple of months it is out of date. Sometimes we just need to go on a kind of cleaning house phase, like we do when refactoring code. Take a look at all the documentation. Is it useful? Does duplicate information exist somewhere else? Is it old and broken?
It is useful to take some time and just review the documentation that is out there and dust it off a bit, bringing it at least a bit closer to reality.