The Modern Book Burning

Book burning.

It has long been known that the burning of books was a sign of a revolution. But it often didn’t become a revolution that history looked kindly upon.

Information was lost.
People were disgraced.
Society at large paid the price.

Future generations often carry the handicap of this missing knowledge.

How did certain people live?
How were such historical buildings built?
etc. etc.

In many cases, the information that is lost is priceless.

A New Kind of Burning

Fast forward to today, our digital age has largely put book burning to rest. So, what is our modern connection to it?

Not writing in the first place.

Think about it.

What was the intention of book burning? To destroy paper? No. To destroy ideas? Yes. Ideas that are never written are doomed to be forgotten.

Many of the world’s foremost productivity gurus, such as Ali Abdaal, say that our brains are wired for ideation, not memory.

So, if you have important ideas that live only in your head, forgetting those ideas accomplishes much of the same thing.

Engineering

Sticky notes. To-do lists. Reminder apps.

We all have a million ways to save our ideas from the forgetful abyss of our everyday. Yet, engineers' jobs are much more complex than our familiar morning routines.

Since our creations are effectively layers upon layers of complexity, surely engineers are the best examples of writers in the world?

Right?

Unfortunately, no. Writing documentation for our colleagues or future selves doesn’t feel “productive.”

It often comes at the end.
It is often easier to move on.
It can be swept aside as something you’ll just remember.
It often gets a pin put into it to do it “later.” Whatever that means.

I say that because I’ve done that.
All of it.

This begs three major questions:

1. What can be done about it?

2. What should be written down?

3. Finally, how should it be written?

Let’s explore them all.

Team Culture

Undocumented concepts are often called “tribal knowledge.” Effectively, it encompasses ideas that aren’t explicitly written down or plainly stated but are nonetheless common practices or expectations.

Team culture can either foster tribal knowledge or destroy that. I recommend we destroy it and replace it with something better.

Well-oiled teams know what needs to be done. This isn’t strictly limited to customer deliverables or shiny interfaces. Sometimes, the developers need to care for themselves.

Again, team culture comes to the rescue. Considering something as done needs to be a defined concept.

Does your application build? It’s not done.
Did you test your application? It’s not done.
Did you ship those updates? It’s still not done.
Did you document critical parts for your future self? Ah, now we’re getting there.

These questions are often formalized into a Definition of Done (DoD) document. Perhaps that might sound too regulated for nimble teams, but even a loose agreement of what developers hold each other accountable to would suffice.

This accountability practice, repeated over and over, eventually becomes part of the team’s culture. You are held responsible for X, Y, and Z, and you return that favor to your teammates.

This recipe varies based on the need and complexity of the project, so finding the sweet spot is essential. I would argue that in the middle of every sweet spot should be documentation.

The PIICC Framework

If there is one thing that is more harmful than too little documentation, it’s too much documentation.

It’s hard to maintain.
It’s often out-of-date.
It’s hard to find what you need.
It’s often full of repeated information.

As teams agree to document ideas, they must also establish what to document.

I limit my documentation to five things embodied in an idea I call the PIICC Framework (pronounced like “pick”):

1. Practices: This documentation is best for project beginners. What architecture are you using? What systems do you integrate with? What are high-level concepts that everyone should know? The documentation at this level is likely established early on and requires very little maintenance. It sets the tone and direction of the code.

2. Interfaces: Interfaces refer to compact modules that encompass a complete idea. For instance, authentication is essential to many applications and can be considered a single idea. Your interface into this authentication concept is essential, especially as these concepts become very large. How does one use it?
   
   For instance, I use the clean architecture in many of my applications. Most of the layers of this architecture don’t matter to the outside world. Only Use Cases should be consumed as the public interface to other parts of the application. This is what gets documented.

3. Integrations: When one concept needs to leverage parts of another to solve a higher level, more complex problem, this can get confusing fast. Depending on the nature of how the information flows or becomes transformed, this can often be an ideal candidate for documentation. This is especially true when building complex integrations that are part of the system’s core. Putting ideas in writing or diagrams is an ideal way to quickly get a big-picture view of how a concept works.

4. Core: This refers to components like session management, boot sequences, and core concepts that impact nearly every part of the application. These ideas are often very specifically implemented, and knowing how they work is essential. At this level, documenting both the inner workings and their usage can be equally beneficial.

5. Complicated Concepts: Complex or complicated concepts are what I consider to be a mixed bag of anything that you think needs an explanation. While clean code and good naming conventions can sometimes alleviate the need for additional explanation, they often lack context. Why was something written, and what purpose does it serve in the broader context? If I think I’ll be asking that question in the future, those answers are written down.

Don’t just document the how; also document the why.

Why were certain decisions made?
Why didn’t you make another seemingly obvious choice?
What were you thinking at the time? (Trust me, you will be asking this later.)

Sometimes, it makes sense to write out your stream of consciousness as you work through the most difficult concepts. Other times, knowing just the end result is sufficient.

You’ll be able to gauge this based on how hard the problem was and how in over your head you felt.

When Words Fail Us

There is a cliched adage that we all know. “A picture is worth a thousand words.” Well, if that is true, then I say a video is worth a million pictures. I use all three mediums for communication.

• Words: They are easy to maintain, and I recommend them for at least 85% of the documentation. Practices, Interfaces, and Complicated Concepts are great candidates to express in just writing. However, big-picture ideas are often hard to explain.

• Pictures: This is where pictures come into play. Often, when you need to explain how multiple pieces work together, pictures do it best. Specifically, I am referring to diagrams. These diagrams might show the flow of information, a state diagram showing the logic of an algorithm, or it could explain how multiple concepts work together to solve a larger problem.
  
  In general, if I find myself visualizing the pieces of a problem and solution in my head while writing code, a diagram usually follows in short order for others to reference. Therefore, Integrations and Complicated Concepts are great candidates for diagramming.

• Videos: I seldom document through videos since they are hard to maintain, but they can serve a purpose. There are only two occasions where video documentation feels appropriate: when I need to show a progression or change over time or when documentation/pictures tend to ramble. Complicated Concepts tend to be the best candidate for videos.
  
  People’s attention spans are short. Videos can make it feel like you’re explaining an idea in person, which holds their interest and increases retention. In short, if I don’t feel as though a picture or diagram accurately conveys my intention, videos are usually the last option.

Conclusion

We are custodians of knowledge. When we fail to preserve it, we fail ourselves and our colleagues.

In all of my work, the PIICC framework has been completely sufficient to communicate and preserve the ideas of my projects. Anything beyond those five reasons tends to be excessive and fall into disrepair.

Always remember and never forget. Writing down the why can be just as important as the how.

After all, it’s about preserving ideas that matter. Your future self will thank you for your efforts today.