Browsed by
Tag: knowledge management

Better Ways Of Storing Product Knowledge

Better Ways Of Storing Product Knowledge

So, the Brain-Format is not that good. Which is? To answer that, let’s first discuss the ideal attributes of a product knowledge and of the place we would keep the knowledge in, the repository. We shall start with the basic expectations from the documentation itself, and later discuss the expectations from the repository.
But before we begin, I would like to make a point – on my previous post I got feedback that I probably should not use the term ‘knowledge’, as it is too heavy a term for the simple ‘information’. Well, I disagree. I believe, knowledge in simple terms, is information in usable format, which includes the insights from the information, which of course, are not part of the information itself. It is processed information, and that is what differentiates it. This difference also highlights the importance of this information and that importance also happens to be the goal behind writing down these thoughts.
Now that it is clear, shall we begin?
The first and foremost point is that the product knowledge is better treated like the product code itself. Is that too much to ask? Consider this – we need the product knowledge to always be relevant. For it to be relevant it needs to be updated, it should reflect the latest changes and enhancements done to the product; in effect it is highly likely that it will be modified every time the code is modified. Hence, is it wrong to expect the same flexibility from the documentation that we come expect from the code? Why should we not apply the same quality guidelines? In general terms, should it not be as maintainable as the code itself?
So, the first list is of attributes of the knowledge storage format:
    1. Easy to create: It applies to new documentation, and new additions to existing documentation. Whatever the format, it should not require huge assembly or lot of people or say, multiple approvals.
    2. Easy to maintain: This attribute is rather an abstract one, and many points below shall touch on this in greater detail. (Clean Code, anyone?)
    3. Easy to extend: Extend, in context of documentation means that it should be possible to combine documents to bring related information together, without duplication, It could be through a link to the information, but best would be the ability to embed.
    4. Easy to use: What is the use of the documentation? It should be easy to read/watch/listen/touch/smell/taste etc. (Well, maybe not touch or smell, or taste..)
    5. Should be DRY: This directly relates to the ‘extend’ requirement, it should be possible to have a single authoritative representation of the knowledge.
    6. Presentable: But of course, we want to use it don’t we? We need to like it!
There are many more analogies we can draw, but I think these are enough to convey the point that it should be built with almost the same principles as the code. Now, we take on the documentation repository and also discuss some non-functional requirements that apply to do the documentation but not necessarily to code:
  1. Access Control: Does it need to be discussed? Of course we need access control, and multiple levels of control: Access to read, write/edit, to delete, and the access to grant access should all be controllable. Even better if we could integrate with the corporate account management system and also set roles.
  2. Record History: For the same reason as code, we need a way to undo (and also blame people) any changes done to documents, including restoring deleted content.
  3. Portable: Yes, portable. The knowledge is not only for developers, it is also for the marketing members of the team, the business analysts and the management. We cannot expect that these guys, whose job is to go out and meet people can always have access to internet and VPN. That makes it a non-functional requirement that the knowledge be portable in full or at-least in part. I imagine some companies having problem with this, but those who use distributed version control systems like Git, should not really worry; they are trusting their teams with the working code, knowledge is not going to cause any new special problems.
  4. Lightweight: It should be light on resources. Resources of all sorts, be it storage, network, computing power, but most importantly on the (arguably) costliest resource on the team: ‘user time’.
  5. Searchable: It should be possible to search within the repository by various categories, tags and of course the content.
  6. Shareable: Shareable by either exporting or by providing a reference pointing to the exact content, like a URL.
  7. Encourage Contribution: This is likely the most neglected but probably the most important requirement. If after being all this, the repository does not appeal to people, it is going stale real soon.
Phew..! However, the list is far from complete. But I think I have made my point, so now we’re off to the next task: Looking for a format and a repository that fits all these criteria! Till then, coke anyone?
Worst Place To Keep Your Product Documentation: Human Brains

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.