Skip to main content

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?


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…