Do you recall that feeling when you've read (in a blog post, tech book, or whitepaper) something you've liked so much (new method, approach, or technique) that you couldn't wait until you try it in action?
Maybe you were even surprised: "OMG, it's so obvious. Why didn't I come up with something like that myself?"
Then you tried to implement it on the next occasion and failed. Repeatedly. What caused you a lot of frustration: "C'mon. That is supposed to be so simple. The way it was presented was so logical and clear. Why are we failing? What is wrong with us?!"
I'll tell you who to ask.
Anton Chekhov.
And his gun :)
"Chekhov's gun" is a prevalent principle in writing fiction, coined (and well-described in numerous letters) by famous Russian playwright - Anton Checkhov. One can summarize it this way:
Everything you put in a story has to have a (not necessarily immediate) use. If something has no use, it is an unjustified clutter and should be removed.
E.g., if there's a description of a loaded gun hanging on a wall, this gun has to fire (even if it's few chapters later). So now you know why it's called Checkhov's "gun" :)
Why is this principle so crucial for fiction creators? It makes the stories more credible, easier to follow, more fluent to read. The cause and effect sequence in the flow of scenes is more comprehensible when not cluttered with unnecessary debris that draws attention in all the wrong directions.
Hmm, wait. Weren't we supposed to talk about professional documents (tech blogs/books/whitepapers)? Yes, indeed. But apparently, this principle applies to engineering writing as well, regardless of whether we describe tech-agnostic architecture models or deeply technical framework usage intricacies.
To put it bluntly: the author has a single goal - presenting an idea and convincing us (the readers) about its usefulness/correctness/veracity. That's the only thing that matters, and to succeed, a lot can (even should!) be sacrificed, e.g.:
- "the happy path" is far easier to cover than all of those sub-scenarios when something goes wrong
- in reality, many problems do overlap, interweave and influence each other - so the author typically cherry-picks a single issue (or a bunch of strongly correlated ones) to focus on
- some conclusions/findings are presented as simple single sentence statements (hereby suggesting their obviousness) - while in fact there may be months (or even more) of complex work that was leading to them (but can be omitted here, for the sake of brevity)
So the author is removing as much as possible to achieve the highest possible clarity (regarding one single, narrow problem (s)he focuses on). That sounds like a good plan (and a secret of pro-level tech writing).
However, that's not how reality looks like.
Real-life.
Real-life is full of all those distractors. In real life:
- problems are not labeled (they don't have to be unequivocally identified either)
- fact relationships are not tagged as causation or correlation
- idea duplicates are not marked with a crossed line
Tackling all that by mapping the overwhelming reality into a simplified conceptual model (with a lot of filtering on the way ...) is probably the greatest of all professional challenges we face on a daily basis (I call it an AUC path: awareness -> understanding -> clarity). But this fact is considered so obvious that it's not mentioned in all those blog posts, tutorials, and whitepapers. So sometimes we tend to forget about it ...
I'm not blaming the authors - the brevity and crystal-clear focus are the only way to go if an author wants her/his message to be crisp and understandable. It is instead a nudge and a reminder for us, the readers:
- Real-life is surprisingly stingy when it comes to silver bullets ...
- Trying to adopt someone else's idea (treating it as a prescription) without an in-depth understanding (of WHY, not just WHAT and HOW) rarely ends well (ref.: cargo cults).
- There's a popular saying in football (unf. I can't recall the author) - "for every virtuoso playing the piano, there have to be few tough guys to carry it for him". You can put this observation in the engineering context by saying: "even the brightest new idea requires a lot of accompanying mundane (and frequently tedious & less satisfying) effort to work".
