A practical approach to maintaining living documentation
Keeping all of your documentation up-to-date all the time isn't realistic. Unless, that is, you divert all your attention to documentation and stop what you're supposed to be doing. Even then, if your organization is of any size, it's too big a task for the average EA team. With all the hype around automation, we shouldn't confuse the concept of living documentation, i.e. documentation that is continuously being edited and updated, with the goal of keeping your entire documentation continuously up-to-date. Firstly, the former doesn't depend on the latter. Secondly, the latter isn't a worthwhile aim anyway - remember, the purpose is to make informed decisions. To achieve this, you don't need everything to be continuously updated.
That last part is only true, however, as long as you know the gap, so that you know what part of your documentation you need to review and update in order to make that informed decision. Now, to know the gap, you need to know
- What is the most up-to-date information at hand?
- When was the information last updated?
- Who was it that last updated or verified it?
- How was it last updated?
Point 1. is the reason for which we strive towards living documentation. Living documentation allows you to call off the search for more data and focus on questions 2, 3 and 4. In fact, without knowing the answer to question 1, you might never get to the other three questions altogether because you'll likely need to start afresh anyway. We hear from EAs all the time, how change projects include a lengthy and costly mapping phase only because the volume of fragmented, dispersed and duplicated documentation hinders any trust in the documentation.
Points 2, 3 and 4 on the other hand have all to do with transparency and traceability, which is what is needed to gauge whether the information at hand is good enough to base a decision on, or whether it needs validating or updating. Using these criteria, you can narrow down the scope of your information gathering to only what is relevant to the impending decision, and preferably only to the parts you don't trust. Therefore, while some parts of your documentation might be continuously updated thanks to automation, those parts that aren't, need only be updated when the need arises.
If EA tools are to remove the bottlenecks in effective decision making, they must facilitate the easy identification of that relevant subset of your documentation, a task practically impossible if all of your documentation is merely consisting of free form such as text and images. Ardoq's graph model brings structure to your documentation that will allow you to easily and dynamically separate what parts are relevant today from those that aren't, as well as what parts you trust from those that will need reviewing.