Skip to main content

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.


Popular posts from this blog

Using Docker and a Private Registry with VPN On Windows

Wasn’t that a very specific title? Docker has a very good documentation and reading that alone is enough for most of the straightforward tasks we might want to do. But as always some practical tasks are not straightforward, hence this blog. What we are going to see here today is how to setup docker toolbox on a Windows machine, make it work even when VPN is connected, make it talk to a private, insecure docker registry (that is why VPN) and configure it so it can run docker compose and see how we can set this config as a one-time activity. That’s quite a mouthful, but yes this is what we are going to do. All ready? Let us begin then.

Install Docker ToolboxGo and download the docker toolbox and install it. That should create a shortcut called “Docker Quickstart Terminal”. Run it. That should show you an error about virtualization.

Enable VirtualizationRestart your machine, enter the BIOS settings and enable virtualization. It may be under advanced settings. On this Laptop, it is under th…

Yet another packager for node

Yet another packager for node There are so many packaging systems for node already, or maybe not as many, so here I am presenting another way to package your applications into an self extracting executable that has no dependencies. Ah well, a few dependencies, like the processor architecture, and Linux operating system may be, but that is all. What is it? It is a modified shell script originally used to create self-extracting and installing applications for Linux platforms. What it does is, it creates a tarball which includes your code, the modules it depends on, the specific node binary it uses, and appends it to a script with the command to execute your code. It is essentially a binary merge of the files, the shell script and the tar.This is not something new, people have used such a system in the past to deliver applications for Linux, every time you see an obscenely large ‘.sh’ file (for being that, a shell file) that can install or execute an application without requiring any ot…

Opinionless Comparison of Spring And Guice as DI frameworks

Recently I had to delve into the play framework for a particular microservice at work. Now it is not exactly new, nor is Guice, nor DI, but coming from Spring world it was still a big shift in approach. There is a lot of documentation comparing Spring with Guice, stating which is better, why and how. In general these articles discuss specific points where these two frameworks differ in their approaches and which approach seems better to the author. I am not sure these articles really help someone trying to take a dip in the other framework. We know the differing opinions, as they are stated by the authors of the respective frameworks in their own documentation as well, another person (article’s author) reiterating it with an incomplete comparison of these frameworks does not sound helpful. What would work much better is a direct mapping of features, without author’s opinion (Didn’t this sound like an opinion). That should help someone getting into Spring from Guice world or vice a ver…