README.md as psuedocode
I recently started a REACT project where I wanted to explore how much more of the process could be automated. When I started using Vite to build it was so quick! It really shows the value of repeatable background processes to productivity. So let’s capitalize on that…
With automation in mind, I captured each minute detail of the process involved with starting up the project.
Once I had built and pushed, I added a README file. Without much deliberation I pasted the process steps into it. The numbered steps pasted in like code. I realized that I could use it as a starting point to write a shell script. It’s psuedocode.
And that got me thinking about how project readme files have evolved along with what we expect of them. At one time they were a file I would only open if I was stuck in the “getting started” phase. Then I encountered some that were a bit better prepared and used them as a reference for re-installing or rebuilding a project. After working on a few projects like that, finding a boilerplate or marketing-oriented readme would actually turn me off about the project. I think Github should get some credit for providing the environment for this.
Have I arrived at another stage of this evolution? Is the readme file (for my own private projects, mind you) a living document? A proposal for how to automated until we reach the ideal, single step?