WHY README?!
There will be cats.
You should read this post to find out why it is insistent that you should read it. But you should also read this post to learn what a README is, why you should read them, and most importantly, why you should always include one in your code development projects. And there may be cats… read on to discover.
Why
READMEs are basically the cover page to your project. They tell the explorer of the internet who has encountered your code what it does (or aims to), how they can interact with the code, any necessary prerequisites in terms of running software or background knowledge, and how to get your project started on their computer. This is valuable information and saves the user a good bit of detective work. Documentation matters!
Content
The popular code hosting and version control platform, Github, asks you to create a README file when you first initialize a repository on the site. However, I find this is a bit like asking you to decide on a career path when you’ve barely finished High School, it doesn’t necessarily lead to the most well-informed choices. So sometimes it is best to simply begin the project and leave the content undecided until later.
When you are ready to write that README, what should its content even consist of? There are a few things that are definitely essential to include for all types of projects and some that are more applicable only to larger projects with multiple contributors and lots of eyeballs on them. Knowing what to include really comes down to thinking critically about who your target audience will be and their level of background knowledge of your work. Below is a run down of the basic essentials and notes about what can be included as the project grows.
Basics (should always be included)
- Title and Description so that everyone is on the same page about the purpose of your project.
- Table of Contents for an outline of your README which can include internal links so readers can skip to the relevant sections.
- Setup instructions to explain how your project can be run on a reader’s local machine.
- Contributors, because people should always get credit for their work and you’d like to stay on the good side of your wonderful collaborators.
Extras (for knowledgeable audiences and overachieving devs)
- Visuals in the form of code snippets, screenshots of front-end interface, maybe a helpful chart.
- Next steps including your vision for the future of the project, improvements, broadening scope, and known issues. This shows you know your work is not done (is it ever?) and starts the conversation for…
- Contributions accepted? If yes, include instructions for how to submit feedback, via a pull request or by your preferred communication channel (email, messaging platform, etc.)
Markdown
Now we don’t just want this README to look like a word doc file of basic blocks of text with hardly any formatting, no separation, and no sparkles! No, we want this README to allow anyone who comes across our project to be able to quickly read, understand, and implement the content. We have created it for the express purpose of making the user’s life easier. To that end, we need to use Markdown. Markdown is
“a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.”
Markdown provides us with all of the basic text beautifying features such as bold, italics, and font size. But there’s so much more that can be used to make code blacks stand out and your document to be more easily navigable. Below are some of my favorites.
- Tables — Information looks much prettier and more organized when there are lines around it to separate it from its friends. The markdown syntax to create a table is relatively straightforward: dashes ( — ) to designate horizontal row separation and pipes ( | ) for vertical column delineation. This looks like:
- Internal links — to other sections of your document in case readers want to skip to a particular section. In Markdown this is achieved by first creating a section heading preceded by a pound sign
#Learn About Cats. The anchor link is everything starting with the pound sign but all lowercase and spaces replaced with hyphens#learn-about-cats. Anywhere you want to link to a particular section (like in a table of contents!) you would write the display text in square brackets followed by the anchor link in parentheses[Go to Learn About Cats section!](#learn-about-cats). - Code Syntax highlighting — one of the best parts about code editors is that they make different parts of your code different colors. Markdown has a way to do this for code blocks included in your README! Simply insert three backticks ( ``` ) on either side of your code block and indicate the code language to the right of the opening fence to trigger the highlighting feature.
There is a Markdown repo on Github that patiently lays out all the ways you can use the awesomeness of Markdown to create readable, linkable, understandable READMEs that make your users, collaborators, students, and potential future employers excited about reading about your work before they experience it.
Now go forth and create beautiful READMEs. The cats will guide you.
Readers should not feel like this:
With your READMEs, they should feel like this:
Resources I loved
For content:
For Markdown:
