Worst Place To Keep Your Product Documentation: Human Brains

One thing I can say from my experience with the products that I have worked on is this - documentation of a product is nearly as important as the code itself, and there should be a comparable amount of effort to keep it usable. Of course, it won’t earn you money-wise, but also won’t create new competition if it leaks either. But does that make the documentation any less important?
What it can do though, is it can save you money and time. It saves time when a new member joins, it saves time when a change is needed: to functionality or to technology, it saves time when requirements are conveyed to a vendor or details to a potential client. It takes the burden off your head, because you no longer have to remember things, except for remembering to document what you know. It is important to secure it, for if it leaks, your competitors can learn from your design, and that can potentially create new competitors. More importantly, it can create immediate threats, because knowing your architecture makes it easy to attack products. (Open Source case is different.)

Despite all these reasons, there is a reluctance to maintain the product documentation in document form! Products rely on team members to remember the technical details and functional flows, they rely on members to convey this knowledge to every new member, they rely on existing members to recollect it when the time comes, and members with all this knowledge to be with them - forever! It can’t work, it has been seen to not work, and yet, we insist!

If it is not yet clear, I haven’t been a great fan of this strategy. Here is why:
  1. No one can remember it all even if someone does, no one can always recollect it at the right time.
  2. When it comes to conveying the knowledge, people tend to convey only what is required for the current task at hand, not the full picture. I am not saying that it is wrong, because at that time that is the only knowledge required. But this process requires a long time for the new member to get the full picture, and hence, to be more productive. You can conduct sessions, but again we are expecting people to remember and recollect what was told to them only once (or twice)!
  3. Then there is the problem of members being reluctant to convey, having vested interests in not transferring the knowledge. The argument can be made that building a cooperative team can solve this, but we know how hard it is build a all-the-time cooperating, motivated team, we will accept it.
  4. Unavailability of ‘the person who knows the answer’ is hard to argue with. People can be unavailable for multiple reasons: they could be away from the office, involved in a different task, travelling for business purposes, unwell, on leave, not being reachable at the moment of the crisis and what not.
  5. And again, people switch jobs - we can’t expect every experienced employee to work with us forever. And even if they did, refer point 4.

And even after all this, people can get hit by a car, or a flowerpot in the head and get amnesia! My point is, can we leave the stability of our product to such things? There are better ways to handle this knowledge. Better, proven ways.

I think at this point it should be clear that we are talking about knowledge of the product. This does not only include the requirement documents, High and low level technical design documents or user-stories, acceptance criteria, issues raised in the agile tracking systems but also the insights, the gists, the summaries, the diagrams, the communications, MOMs, presentations, sessions in searchable, easily retrievable and referable form. (Too late in a post to define the core subject, but better late than never!)

I would not want to get into the details on how to store documentation outside of human brains right away, but understanding that we need to is the first step in that direction.

No comments:

Post a Comment

We need to talk, says one microservice to another

‘But how?’ asks the other service! Ever wondered how we communicate? One would not believe how complex and multi-step process it is. It in...