Readme -> Build Instructions -> Automation

Ever since I started using GitHub I have followed their advice and included a README file that describes what the project is about, and maybe some details about how to use it, build it or what the intentions are or were.

To be honest, I rarely return to my projects, and read the README files more rarely still. Recently I have been questioning cases where a good portion of the README is devoted to instructions. Wouldn’t I be better off writing scripts instead of what is essentially psuedocode?

When I recently started using Python I encountered some new build steps and concepts that I needed to capture. I heard that little nag in the back of my mind “You could just write this as a script and stop repeating yourself”…

After almost doing this for a third time I finally listened. Instead of writing the commands in the IDE terminal, I wrote them in a text editor and executed them. I added more steps and repeated. I found myself questioning how, when and where the steps were operating.

I recently wrote about a situation where I needed to call a script using the source command instead of ./ – a perfect example.

The peril of taking this approach is that one can get waylaid. The script can take longer to perfect than the code it is operating on. Discipline is required!

In some cases it may be acceptable to include a note to the script user describing a manual step they will need to take if it is beyond the scope of time required to write a script to cover it. As I consider this I realize that it would probably be a good idea to include a TODO note with it.

In the best case, a fully scripted build will be ready to incorporate in a larger integration. A point that will prompt finding and solving the TODO echos that would have slowed down the development and might have made the automation un-necessary.