The agile manifesto came along and suggested we focus on “working software over comprehensive documentation” which by some has unfortunately been taken to mean “no documentation”. Let’s just say there’s a significant grey area between the extremes of “comprehensive” and “none-at-all”.
Personally I’m aware that I fall more into the “comprehensive” camp than the other though I put this down to the fact that; for me, putting things down on paper is a great way of helping me think things through. For me, documentation is a design tool.
On the other hand, wikis…! I used to see wikis as a saviour from the hours/days/weeks spent reviewing documents and trying to keep content consistent across multiple work-products. Finally a tool where I can update in once place, link to other content and focus on the detail without the endless repetition. Something in support of the agile manifesto which endeavours to provide enough documentation without going overboard on it. Unfortunately recent experience has exposed a few issues with this.
Table below compares the two.
| Documents | Wikis | |
| For | Good formatting control. Easy to provide a historic record. Provides a point of contract sign-off. Easy to work offline. Generally accessible. | Highly used critical content is maintained. Good sharing within the team. Hyperlinking – easy to reference other content. Promotes short/succinct content. Good historic record (one is kept automatically). |
| Against | You have a naïve hope that someone will read it. Promotes bloat and duplication. Promotes the MS monopoly. Poorly maintained. Rapidly goes stale. | Promotes the illusion of quality. Poor formatting control. Requires online connectivity. Low usage detail becomes rapidly out of date. Poor sharing outside of the team. Hyperlinking – nothing is ever in one place. Poor historic record (too may fine grain changes makes finding a version difficult). |
Hyperlinks, like the connections in relational databases, are really cool and to my mind often more important than the content itself. That wikis makes such a poor job of maintaining these links is; in my view, a significant flaw in their nature. The web benefits from such loose coupling through competition between content providers (i.e. websites) but wikis – as often maintained by internal departments – don’t have the interested user base or competitive stimulus to make this model work consistently well. Documents just side-step the issue by duplicating content.
So wikis should work well to maintain operational documentation where the user base has a vested interest in ensuring the content is maintained. Just so they don’t get called out at 3am on Sunday morning because no-one knows the location of a database or what script to run to restart the system.
Documents on the other hand should work better as design products and contractual documents which all parties need to agree on at a fixed point and which aren’t going to be turned to very often. Ten commandments stuff.
The problem is the bit connecting the two and the passage of time and decay turning truth into lies. The matrix connecting requirements and solution, architecture and operations, theory and practice, design and build, dogma and pragmatism. Where the “why?” is lost and forgotten, myth becomes currency and where the rain dance needed each time the database fails-over originates. Not so much the whole truth and nothing but the truth, as truth in parts, assumptions throughout and lies overall.
The solution may be to spend more effort maintaining the repositories of knowledge – whether it’s documents, wikis or stone tablets sent from above. It’s just a shame that effort costs so much and is seen as being worth so little by most whilst providing the dogmatic few with the zeal to pursue a pointless agenda.
No comments:
Post a Comment