Writing a README
I’ve spent a lot of time working on my most recent project. Continuously looking for ways to refactor, improve and elevate the level of my code and in turn, the application itself. Only to realize that I have not constructed a README file before I deploy. I’m sure that I am not the first developer to encounter this situation, and I’m certain that I will not be the last. This has inspired me to share with you how to create a README file, using the common ‘Markdown’ syntax.
What, why, when, where and how?
What: A text file that introduces anyone viewing your project to it, and also explains what the project is.
Why: It is simply a way to answer common questions that your audience may have regarding installation, usage and contribution if applicable.
When: Before you share your project with the public! Try to start the habit of creating the README as one of the first, if not the first file in your top level directory.
Where: Top level of your application directory.
How: The most common file type is Markdown (README.md). Check out CommonMark. It provides great guidance in using the compatible spec of Markdown.
** Side note: most code editors (I personally use VisualStudioCode, provide the ability to see your README preview, instead of the raw text file. **
Structure and suggestions for your README file
The first thing to include, and maybe the most obvious is the name of your application. The Markdown Reference section on CommonMark provides the syntax needed for some light formatting. Such as, headers, italics, links, images, etc.
Next, you’ll want to let people know what your application does specifically with a description section. What inspired the application? Provide context as to how and who it was built for with references (perhaps links) for aspects that potential readers may not be familiar with. If you imported some sort of library for your project that is featured throughout your application, this is the place to reference that.
If you really want to up the level of presentation for your README, and push to be as professional as possible. Badges are something that you’ll want to include! For example, with a Ruby on Rails backend I’ve used several Gems that I want to let readers know about. Shields.io will provide you with a template for the markdown syntax you will need.
You may want to use visuals that could be useful for your audience. Screenshots, videos or even gifs are useful and popular in many README’s. The ttygif is a useful tool you can use to convert files into gif files. Ironically enough, their README starts with a gif.
Installation: This is going to be the meat of your README. Here is where you will tell your audience how to install your application and use it. It is best to deliver installation instructions as though the reader is a novice. Try your best not to assume anything about the audience’s knowledge of installation and setup.
If desired, or appropriate you can also offer a way for your audience to reach out with any issues they may experience. For example, some sort of issue tracker, a chat room or just a simple email could suffice.
Finally, it is important that you give the audience an idea of where the application stands in terms of development and whether or not it is open for contribution from other developers. Provide a ‘roadmap’ as to future plans for the application if there are any. Also if development has be delayed in some way shape or form, or has even stopped completely, you’ll want to let your audience know. Transparency is important!
Like any other documentation or project, it is both appropriate and responsible to give credit to other contributors. At the very least, a simple show of appreciation to any contributors is the polite thing to do! Everyone likes to feel appreciated.
Make the most of your time!
Remember, you are putting your time and energy into your application. Possibly collaborating with others. All of that energy could go to waste without a simple text file (README) in your project directory. If your audience does not understand what your application is, how to install and use it — what is the point of spending all the time in building the program.
Your README file is going to be the door into your application. Make sure you give your audience the key, with a clear, concise and strong README file that reflects the quality of your code and application.
