Documentation Oriented Programming
/ 3 min read
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.
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.
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:
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.
If you are interested in this topic, check the following bits and references you can dive into.
- Check out what Architectural Decision Records are (ADR)
- The Code Comprehension Problem
- Conor from Roam Research’s video on how he uses Roam to make architectural decisions.
- Jest tests driven from comments
- Julia Evan’s suggestion for you to always share your debugging stories
- How to Take Smart Notes
- Modalble development environment
If you are interested in this topic and would like to know more about the tools I use, tweet at me @Andrei_Calazans = )