skip to content
Andrei Calazans

Documentation Oriented Programming

/ 3 min read

engineering

There are all types of “Oriented-Programming”:

  • Object Oriented Programming (OOO)
  • Data Oriented Programming (DOP?)
  • Domain Oriented Programming (DOP? 2)
  • Test Driven Development (or programming 😅)(TDP?)

You get the point. It is just a pattern or method you can apply while writing code.

So, how about we introduce one new paradigm!

Documentation Oriented Programming (Yet another DOP)

I tweeted about this idea on 26th of May, 2020.

How about a “Documentation Oriented Programming”. You write a document as you work on the problem with the how/what/why. It could be:

  • shared
  • referenced
  • posted

@kentcdodds ‘s step 2 and 3 in one https://bit.ly/3c5Qvsj plus @swyx learn in public in an do in public twist?

Tweet

At A Personal Level

In my programming career, I noticed the following things happening over and over:

  • Solving the same technical problem.
  • Answering the same technical questions.
  • Giving the same guidance to different folks.

From this, I came to a realization of how the source of these three items is somewhat the same - programming/experienced knowledge.

While I can undervalue my time and always spend 30 minutes writing a response or discoursing on how something was achieved, it makes more sense to optimize this (of course, we must optimize, how will I live to my title of software engineer if optimization is not in my head 😂).

This was when I started taking a “Documentation Oriented Programming” approach.

Clarity & Writing

Think Before You Do -> Write Before You Do

They say you should think, ponder, plan before you take action. However, if you agree with me that writing is the medium for thinking, by writing you are thinking.

1/ Why you need to document things to improve your decision-making, a thread:

“The first principle is that you must not fool yourself and you are the easiest person to fool.” ~Richard P. Feynman

Tweet

Plus, being able to document your thoughts with clarity is a senior level skill.

Shawn Wang goes over this in his book “Coding Career” and finds evidence from interviewing a retired software developer who mentions that the important skills to have are the ability to document and speak with clarity.

Not to mention, he also follows up with CircleCI’s promotion ladder:

Here is @CircleCI ‘s ladder. The thing they use to evaluate and promote people.

”Technical skills” is line 7-13. Lines 14-33?

  • Dealing with ambiguity
  • Knowledge sharing
  • Handling disagreement
  • Mentoring
  • Product Thinking

Tweet

For the times I felt successful at helping others, it has mostly been because I had done a good job documenting my discovery process and, I simply shared what I had documented.

At A Company/Project Level

Just ask yourself, at the current company/project you are at, can someone onboard without help? If the answer is no than you could clearly benefit from a documentation oriented approach.

While the post talks about programming, documenting is appliable to everything. In my life, I try to document everything I can.

Unstructured Extras

If you are interested in this topic, check the following bits and references you can dive into.

Final Words

If you are interested in this topic and would like to know more about the tools I use, tweet at me @Andrei_Calazans = )