Readme.md (or be ignored)

We all like to know what we are going to be getting before we commit time, money and/or effort into it. Would you hire someone just by hearing their name, or would you prefer seeing their CV and having an idea of what skills they will bring?

The same thing applies to your code on the internet. Without a detailed explanation of what the code does, and maybe some examples your code will most likely be ignored.

Github (and most source code apps) display the readme.md file as the first page people see when they access your repository. You can use this file to give as much or as little information as you like. When I am searching for a project that will assist me in what I'm doing I'll always read the readme before looking any further. I hope to be able to judge fit-for-purpose from the readme.

The second thing I look for are examples on how to use the project. If you have a A-level project maybe I'll look to see if there is a separate demos repository under your name, but mostly I expect to see a directory called demos or examples or something similar.

Lets use an example of how I find projects and libraries that will do something I need. Lets take an example where I have a gpx track that I'd like to visualise. I mostly use PHP or javascript so lets try find a suitable PHP library:

1. Search for Key words ("gpx track")
2. Filter for the language I need ("php)
3. Open the first 5 in separate tabs (skipping archived projects)
4. Look for each with a read me (in this example tabs 2 and 4 get closed as they have no useful readme information)
5. Review each for suitability (tab 1 is removed as its for "Known", I have no idea what that is)
6. Look for Examples (tab 1 does not have examples but nicely documented in readme for me to copy)
7. I now have 2 tabs left, tab 1 has a nice readme and a tests folder, tab 2 has a readme with explanations and an examples directory with 2 examples.
8. I can now evaluate them both. As tab 2 has clear examples I'd try it first.

Without a clear readme, and a clear indication that there are examples I would not have selected these 2 projects for evaluation.

If you want people to try and then use your project, make sure you explain what the project does (i.e. a Readme.md file) and then show people how to use the project. I personally prefer finding examples that I can download as in and run them, but second best is well documented example usage.

Do your projects have a Read.me?

PS. The "md" file extension is for markdown a simple method of formatting documents.

PPS. Did anyone try my example to see what the projects were. If you notice anything special about the last one I chose I'd love to hear about it in the comments.

PPS. I try and follow this on work related projects as well. I don't know if someone in 3 years time needs to use the library I created at work so a readme is a critical docuemnt to leave behind.

PPPS. Here is a list of awesome readmes: https://github.com/matiassingers/awesome-readme