So if a team is consistently creating comprehensive documentation following all
the good practices, what is goes wrong?
To understand the problem, you should look at the requirement document as a
“diff” or a “patch” on your product. You have an existing version of live
product, you create and give the
diff to your engineering team, and they
“apply” it and you have a new version of the product.
So far so good, now what happens to those requirement documents once the feature
is live? Can someone go through those documents after 6 months, and understand
your current product? Of course not, you did not go through this “diff”/“apply”
phase just once, you must have a lot of similar cycles play out.
Imagine if the goal of the documentation was for someone to understand how your
product works. Of course, one can understand how the product works by going
through the product. But that’s tedious. There are too many roles and journeys
and edge cases. Product is the most accurate documentation of the product,
followed closely by the source code. But if your goal is to understand how your
product works, going through the live product or source code is really
ineffecient, time consuming, and prone to human errors. There may be strong
invariants and philosophies of your products that people may not deduce from
just reading the code or interacting the product.
Everyone tells you documentation is important, not just because it is important
while a feature is being developed, but also because of the hope that after the
feature is developed and someone new joins, or you have forgotten how precisely
the feature works after a few months, you do not have to waste time reverse
engineering your product or code to understand how feature works, that you do
not have bring everyone who implemented the feature in same room and have a zoom
call to rely on their memory of how things are, which is both error prone, and
time consuming, and primary reason teams get stuck, too many meetings!
There are other problems with documentation when following this workflow. In
many cases the documentation would talk about both things that may happen in
long run, and things that have been identified as minimal items to be
implemented. The demarcation of what is long term vision vs what is to go for
immediate development may not be obvious from reading the documentation. Sure
someone may have created a section for whats really to go live, what can wait,
but it may be inaccurate. Further, even after things go for development, and
the release is getting delayed the cut down scope is often again cut down. And
often this second cut down scope would only be communicated in war rooms and
Jira tickets, and the original document would not be updated. Some could do it
with utmost care, sure, but history teaches us humans are prone to error despite
So let’s empathise with the poor chap or chappie for a moment, they have to go
through the documentaiton to understand how things are, they have to mentally
“merge” all the “released” requirement documents, somehow keep track of what of
this is released and what is still planned, or was planned but we have changed
out mind about it. No wonder people feel like reaching out to others on zoom
calls instead of going through this process, it’s just not humanly possible to
get accurate picture based on documentation following this workflow.
A document that is 10% in-accurate without knowing which 10% is almost useless
because the reader has to suspect every bit, double check everything, will end
up having very low confidence to whatever they deduced based on their reading,
and will feel like talking to others, or trying things out. And if that is the
alternative, why bother with documentation?
And this is what so many teams do today. They will put the documentation of the
feature in a Jira ticket! No one goes through Jira tickets that are closed,
unless investigating some major issue, not to understand how your system works.
People are often just resigned to “documentation is useless”, or “what’s the
point of writing documentation, no one reads them any way!” etc.