TJL #30: Start with writing your README (Daily productivity #5)
Simple tips & tricks to be more productive
Welcome back to Today Jan Learned (TJL) #30. In this newsletter I share the best of what others have figured out already. To get these delivered straight to your inbox, subscribe now
Key insight:
Start with writing your README before you write any code.
Read this if:
You have trouble starting with building.
You have trouble communicating the value of your product to others.
You should probably start with writing a README, but what is README anyway?
What is a README?
A README is a text file that introduces and explains a project. It is a summary of all the information that is needed to understand what the project is about and how to use it.
For example, this is the README of the code of my website.
It explains what the code is, how to set it up, and how to use it.
README driven development
Whatever you are building, write your README first.
That’s what Tom Preston-Werner, founder and former CEO of Github, writes in Readme Driven Development (emphasis mine, edited for brevity):
Write your Readme first.
First. As in, before you write any code or tests or behaviours or stories or ANYTHING. I know, I know, we’re programmers, dammit, not tech writers! But that’s where you’re wrong. Writing a Readme is absolutely essential to writing good software. Until you’ve written about your software, you have no idea what you’ll be coding.
Always describe your software first at the highest possible level. Do this in your README. What does it do? How do you set it up? How are others going to use it?
By writing your Readme first you give yourself some pretty significant advantages:
Most importantly, you’re giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organised or what should be included in the Public API. (…)
By doing it this way, you give yourself the opportunity to think a whole project through in its entirety, without too much overhead. This allows you to quickly change your mind without having to change any code.
As a byproduct of writing a Readme in order to know what you need to implement, you’ll have a very nice piece of documentation sitting in front of you. You’ll also find that it’s much easier to write this document at the beginning of the project when your excitement and motivation are at their highest. Retroactively writing a Readme is an absolute drag, and you’re sure to miss all kinds of important details when you do so.
A nice extra benefit is that you, after writing your README, have a solid piece of documentation sitting in front of you and a shopping list of things to build.
It’s a lot simpler to have a discussion based on something written down. It’s easy to talk endlessly and in circles about a problem if nothing is ever put to text. The simple act of writing down a proposed solution means everyone has a concrete idea that can be argued about and iterated upon.
The final and arguably the most important benefit is that writing your README first provides something tangible. Instead of your idea staying floaty inside someone’s head, it becomes a concrete thing you can argue about and iterate upon.
What would the README of this newsletter look like?
Very good question, I hadn’t thought of that. But I guess something like this.
Daily Productivity README
Welcome to the Daily Productivity Newsletter 🚀
Daily Productivity is a newsletter in which I share practical and effective tips on how to get more shit done by making you more productive.
These tips are drawn from the best self-help books, other people’s experiences, and my own.
Every day I will try to share something of value.
I will present it in such a way that you don’t need to read the source material and can immediately apply it to become more productive.
I will also tell you how I used the tip and how you can apply it to your own life.
I hope I write every day. That means that in a year I will have compiled a list of 366 practical tips and tricks that make you more productive.
If you want to tag along for the journey, feel free to subscribe here!
How to apply
So how do you apply this idea? Before writing any code or doing anything, start by writing your README.
Your README is a description of:
What you are building
What it does
How to set it up
How to use it
I put my README in the section here above and I should’ve done this way earlier.
Writing your README first is a great exercise because it clarifies a lot of things like, what it does, what value it adds, how to set it up, and how you expect people to use it.
These are great things to think through ahead of building anything.
What does your README look like?
Previous TJLs
Read my previous TJLs by following on the links down below: