How often do you come back to an old project and find it takes you ages to figure out what you're doing? What do you need to install, how to run it? This is all wasted time.
Public projects use readme.md’s. Just because you're a sole developer doesn’t mean you shouldn’t use one. For many of us, coming back to an old project is akin to picking up someone else's project.
Recently I changed computers and needed to set-up a project again, but it had been some time since I used it. I couldn't remember what I needed to do to run it again.
It took me far longer than it needed to in order to get back to work.
Now I include a readme in every project I make. It doesn't take very long for me to write one and each time I fire up a project and find a README, I thank myself.
Of course, you need to remember to look at the readme.md but it's just about developing the habit to always look for it.
I'll put in any information I need to get started with the project and it will evolve each time to include steps I have missed.
I will also include links relevant to the project, like good tutorials relating to the framework used.
I will include gotchas, things that have tripped me up before so they can't get me again.
Essentially I will include anything that will make my life easier every time I install the project or come back to it after a gap.
Some ideas of things to include:
- Tutorial and documentation links
- Project set-up steps
- Build commands
- Snippets
- Testing information
- Project structure
Sometimes the readme gets a little verbose. In those instances, I will keep the readme to the most important things then start a wiki elsewhere. This is all normal things for open source but we forget to do it for corporate or personal projects but they are still incredibly invaluable.
I am all about making my programming life smooth and less frustrating. Using readme's in every project helps so much with that.
Top comments (0)