First Impressions
If your childhood was anything like mine, you probably heard your mother say more than once, "You never get a second chance to make a first impression." This, of course, was ultimately followed by a rolling of the eyes or anything that constituted a complete distaste for an obvious statement under the guise of being profound. Like all good things from your youth, this naivety will eventually come to an end and at some point in your adult life you will most definitely acknowledge the wisdom in that statement.
If you plan on starting an open source software project, you'll want to remember this advice. Just like combing your hair and brushing your teeth are good practice, having a well written and understandable README file is the key to making sure you grab the attention of the curious and keep the skeptical reading.
My Problem
I recently started a project called, Muse. In my excitement for what I had just accomplished, I hastily told everyone to go check it out. Then I realized a big problem...my README was lacking actual content. Besides having a title, a short description, and an AppVeyor build badge, I had..nothing...nada...zilch. Any seasoned developer knows the sinking feeling that you get when you realize you just released bad code out into the wild...and there's no take backs.
I can hear people saying, "It's just an introduction file, how bad could it be?" Keep in mind this was supposed to be my big hurrah, my moment to shine...and I just bombed it. No one that looked at my code would even know what to do with it at first glance. To my surprise a few brave souls starred it and one even forked it. Many kudos to you for your adventure of the unknown.
Cleaning Up
When I started the project, I was a bit intimidated with the idea of writing something that people would read. I did eventually write that pesky file, but not before learning the hard way. In my first blog post, I confessed that I was afraid and that I would probably embarrass myself but was committed to jump in. Little did I know I'd screw up so soon. In an effort to help someone else that might be struggling with where to start in making an effective README file, here are a few tips:
- Start off with a simple one paragraph overview. Something that gives the reader a good understanding of the scope and purpose of your code without going into too much detail.
- Have some kind of 'Getting Started' section. Something that will enable a potential developer to get up and running with as little guess work as possible. Don't be afraid to go into too much detail...just make sure it's relevant to the project. The easier it is for someone to get started, the more likely they will find your project useful.
- Give credit where credit is due. List any websites or software that are using your code and let people know about the third-party software, if any, that you've used in your own project.
The Heart of Learning
There's this thing I tell my kids when we're driving somewhere and we are either lost or going a different way than we normally go. I tell them, "It's an adventure!". It lightens the mood and lets them know this is just like all the other times and it'll probably work out in the end.
For the first one hundred or so viewers of my code, I may never get that second chance at making a good first impression...but I do know that from this point on, I will get many more first impressions...and many more second chances...and it will probably work out in the end.
It's an adventure!