25
sarena
4y

I am extremely particular about writing good READMEs in my repositories. I make sure that it has everything from prerequisites to run the code and tests on a new machine to how to actually run it (and the tests) and everything in between.

Despite all that I was asked questions that should have been avoided if you had seen the README.

One of these times was by a junior DevOps asking me about an error which was clearly due to him running the code without a virtual environment. Pings me with the entire stacktrace, I go to his desk and tell him to install the environment, which he does. 3 minutes later, another error message.

He was running the wrong script. I go to his desk again. Open the repository. Show him the README. Show him the section titled "To run the pipeline"!

There's a reason they're called README. You're supposed to READ them! 😑

Comments
  • 6
    Good READMEs are great and all, but make sure they're not *too* long - otherwise people will tend not to read any of it.

    Life shouldn't be that way of course, but it is.
  • 3
    @AlmondSauce Agreed. But this particular one was less than 100 lines with to-the-point stuff
  • 1
    @aashimaY When I try out new lib or something new in general, I just want working code samples. If I see that there is NO code example in readme, it's pointless to read.
Add Comment