Essay-Driven Software Development

Today I am going to share a wild idea that actually worked wonders for my own software development efforts. I have been playing with writing essays for my dev work for several months now and I will argue that essays can become a valuable new tool in your toolkit and help you become a better developer as well as a sharper person.

Following this practice you can:

• Reduce wasted effort writing software features
• Resume work faster
• Better communicate pros/cons with your colleagues
• Have traceability of major technical decisions
• Formalize the process for feature proposals
• Increase the likelihood of your feature being implemented
• Have a central repository of know-how and domain knowledge
• Reduce back and forth discussions while implementing features

But before we jump into the details, let’s cover the basics.

How Writing Is Important #

Many successful people would argue that being able to write gives you an enormous edge, especially now when this skill is severely underestimated. Jordan Peterson, Jocko Willing, Tim Ferris, are only a few people who have shared multiple times how being able to write properly can open many doors in your life. According to them, writing allows you to:

• Have clarity of thought
• Communicate more clearly
• More easily find flaws in your ideas/thinking
• Better defend your ideas

It should be obvious that those can have far reaching effects on multiple aspects of your life but I will leave it to you to dive deeper if you are so inclined. You can get started here, here, here, and here.

Now let’s focus on how essays can help you become a better software engineer, CTO, startup founder, you name it.

Essay-Driven Software Development #

The process as a whole is simple and boils down to creating an essay for every feature/idea and trying your best to explain why that particular thing should be built and how.

For my projects, I have a folder called journal where I keep all essays in a Markdown format.

Putting your thoughts into written form will allow you to better assess your ideas and spot any potential problems. Simply the act of writing down your ideas will allow you to tinker with them more easily - rearrange, combine, delete, reformulate. That will significantly increase your bandwidth to formulate a solution or make a decision.

Another benefit is the ability to resume work much faster. We know that context switching is killing us and that Deep Work can help us do more and better work but no matter what we do we will be interrupted and we will need to stop our work. The longer the pause, the worse the impact. I have found that simply reading through my essay will dump all of the needed information in my brain and allow me to continue straight from where I left. Previously I would need a lot more warm-up time to get going.

Since we are dealing with software, you are free to put code into your essay. If applicable, I usually lay out several possible implementations using code or pseudo code and compare and contrast the different options. This has proven immensely helpful in stopping me from going the wrong path.

Once you finish the essay, you will probably have a much better understanding if the feature is even worth doing and what’s the best way to go about implementing it. What you do next is analyze what you have written or share your essay with colleagues for further discussion (if needed). If you must defend your idea, having written the essay should make your case stronger.

If you decide to proceed to implementation, you will continue working on your essay. You will create a new section at the end of your essay where you will write any important decisions or questions that are bound to pop up during the implementation. Software is usually far too complex to expect that everything will go as planned and no issues will occur even if you are using essays. Once a noteworthy question is identified, immediately write it down - again with context and what must be decided. Write down the resolution after the question has been answered. This step is most valuable for historic tracking of decisions and has proven amazingly helpful when you are not sure why something was done in a certain way. This is a very good way of storing knowledge.

Once you are done and the feature is implemented, I tend to write a summary about what was done and how the whole process went.

The Template #

Every essay has a slightly different structure simply because you are dealing with different topics. Nonetheless, I tend to have the following components most of the time:

• Background - what you are talking about and what the context is
• Analysis - how and why your idea is going to work / be implemented
• Experiment & Metrics - the way you are going to measure success of this feature
• Implementation - implementation details
• Summary - highlights of what was done and why

I have decided not to embed a sample software development essay here as the reading experience is not optimal. I did not like the idea of having an article within and article and going full Inception. If you have been intrigued by Essay-Driven Software Development, I have created a companion Github repo where you can take a look at a sample eassay to help you dive deep on the matter. Also, there is a blank template to get you started.

Tips & Tricks #

Here are some guiding principles and advise that I can give after following this practice for about 6 months:

• Just try it, be messy - you should not be perfect. Just start writing and see if the practice adds value to your work.
• Use it for trivial stuff - there are cases where the implementation and the impact seem so obvious but I would encourage you to write an essay even for the more trivial stuff. You will find out that sometimes trivial stuff is not so trivial and that it needs more exploration.
• Essays can be short - Some topics are easy. Some essays are short.
• Code while doing it - yes, you can code while creating your essay. It is kind of the research part of your essay. I regularly go back to the code to check and try things.
• Add code to your essay - I have already mentioned that but it is worth repeating - add code to your essay (you are a software developer after all). That way you will be able to more easily compare various implementations and have it all in one place.

Final Thoughts #

I hope that this kind of approach to writing software can help you become a better at exploring and defending your ideas. Let me know if you have tried something similar or if you are willing to experiment with this approach.

In the end I would suggest to just try it. Ping me in the comment section if you have any questions.

References #

1. Jordan Peterson on the Power of Writing - https://www.youtube.com/watch?v=bfDOoADCfkg
2. Adventurous? You NEED to Learn How to Write - https://www.youtube.com/watch?v=j4f3aHlTe0E
3. How to Use Writing to Sharpen Your Thinking - https://www.youtube.com/watch?v=65U5byDZ55M
4. Improving Your Writing Will Improve Your Thinking - https://www.grammarly.com/blog/improving-your-writing-will-improve-your-thinking/