Explicitness over Implicitness

posted by Matías E. Fernández

This is the second instalment in a series of articles about six core principles that my team, a software development team, and I compiled in order to develop a framework for decision making. The reason for building the framework was to build a common understanding of how we want to work. Writing it down allowed us to easily transfer that knowledge to new colleagues and to spread the word.

In this article I discuss what I think is number one cause for misunderstandings: implicitness, and how you can counter it by making things explicit.

U.S.S. Enterprise NCC-1701-A, top view.


Because people with different background and levels of experience interpret things differently implicitness hinders good communication and causes misunderstandings. Implicit knowledge is hard to access for new team members and makes bringing them up to speed difficult. People do things the way they’re used to, neither are they aligned nor are processes standardised. This makes things error-prone and compromises quality. Making things explicit through documentation and striving for simplicity by following the KISS principle allows standardisation of process and eases maintainability, thus enabling a continual improvement process to improve quality and with it both effectiveness and efficiency.

The Situation

Environments that require a lot of implicit knowledge to perform tasks tend to have a low degree of standardisation. The knowledge of how to do things is in the heads of individuals only. Furthermore different people usually solve similar problems differently corresponding to their personal experience and discretion. Tasks requiring specific domain knowledge get stuck because the required people too busy with other seemingly important tasks. It’s difficult to train new co-workers because they require a lot of help from experienced colleagues who tend to have tight schedules and little time to instruct new peers. People are not aligned and have diverging opinions of what needs to be done and how it needs to be done. As a result it’s the quality that suffers.



Unclear or ambiguous statements can be interpreted and understood differently by different people. This easily leads to misunderstandings which in turn lead to frustration or even anger. (Friedemann Schulz von Thun has researched this topic extensively and is best known for his Four-Sides Modell.)

Long Ramp-Up Times

Whenever a new member joins an environment that lacks clarity, e.g. because no documentation is available or even worse, because documentation is wrong, she will need to figure things out by herself. Often that new member will have to ask co-workers for help and will thus hinder them from doing their planned work. Having to figure things out by oneself will lead to unnecessarily long ramp-up times.

Error-Proneness and Inconsistencies

Because general conditions, priorities, requirements and the like are unclear, people start making own assumptions and implement solutions accordingly. This quickly leads to inconsistencies an errors.


Keep it simple, stupid – KISS

The ultimate goal of every engineer should be to make things simple. While sounding easy, simplicity is often extremely hard to achieve. Simple solutions are about finding the true essence of complex problems. It requires a lot of hard work, thought and experience to find them. There is no cookbook pattern you can follow to find simple solutions to complex problems. The basic idea behind the KISS principle was known to many masterminds, consider the following quotes:

Simplicity is the ultimate sophistication.

– Leonardo da Vinci

Make everything as simple as possible, but not simpler.

– Albert Einstein

One of my favourite quotes on the topic is from Antoine the Saint Exupéry, best remembered for his novell Le Petit Price (The Little Prince):

“It seems that perfection is reached not when there is nothing left to add, but when there is nothing left to take away”

– Antoine de Saint Exupéry


If you’ve read The Phoenix Project you’ll probably know that documentation is one of the first steps towards standardisation. By documenting the steps required to accomplish a certain task, one is able to enforce some level of consistency and quality. Furthermore documentation allows automation by defining a standard way of doing a task. Documentation is probably the most important step to make things explicit.

Peer Reviews

Peer reviews help identify unclear parts, e.g. code, documentation, guidelines etc. that can then be improved. It’s always a good idea to have something examined from different angles.



By making things explicit through documentation, a team gains a common understanding of the documented topic. Everyone can read the documentation and understand how things work or should be done. It opens up the field for discussion and thus for improvement. Documentation can be worked on and continually improved. It defines a standard and creates a basis for aligning processes.

Elevation and Satisfaction

Documentation elevates co-workers in the sense that it enables them to do things which require domain knowledge that they otherwise would have had to laboriously figure out by themselves. Being able to get things done by themselves gives co-workers a deep sense of satisfaction, motivation and time to think of ways to improve processes. When documentation is actively used, people can help improve the documentation and thus improve the effectiveness and efficiency of the organisation. Avoid stale documentation because it will become outdated or even wrong. Resist documenting for the sake of it because the more documentation you have, the more work it will require to keep it up to date.

Better Communication

Explicitness through documentation helps improve communication by setting a common ground. Writing things down materialises ideas that are otherwise difficult to grasp and makes them tangible. Consider this quote attributed to E. M. Forster:

“How do I know what I think until I see what I say”

attributed to E. M. Forster

Too often ideas remain blurry until you write them down or start discussing them with peers. Good communication isn’t easy at all and it thus important that one continually seeks to improve it.


Making things explicit through documentation helps organisations standardise work thus elevating co-worker to perform tasks that they wouldn’t have been able to do otherwise. Peer reviews and active use of documentation enables a continual improvement process through feedback and collaboration ,thereby improving quality and both effectiveness as well as efficiency.

You may want to have a look at this code example demonstrating “Explicitness over Implicitness”.

Thank you Raffael Schmid (@rafschmid) for writing the initial version of this article.

From Dev-Team with