Anyone familiar with writing code knows the importance of good documentation. When written clearly notes and comments can give direction and understanding to those who use your code, or even a refresher for yourself if it’s been awhile since you worked with a certain piece of code.
In this article I will focus on the first instance of this people see, the README. The filename itself signals its importance being written in all-caps. So it might be worth it to make sure you give it some thought!
Note: I will be using examples from Github, but these concepts apply to any README
1. Markdown
The first thing to be familiar with when writing your README is markdown. Markdown is a way to simply style text on the web, such as increasing size, bold, making lists, etc. Though I won’t spend a lot of time on the specifics there are plenty of resources on writing markdown that can help make your documentation stand out and have a better flow. Below are a few resources:
2. What to put in your README
The most basic of READMEs should still include a few main pieces of information.
- Title — What is your app/project called?
- Overview — Why did you start this project?
- Features — What are some key things your project can do?
- Running the project — How could someone else get your code working for them?
- Dependencies — What are the main outside resources your project needs to run?
Title
Simple enough, what do you call this thing? People need to know what to call this awesome new thing you made!
Overview
This should be a quick run through of why you made this project, it’s key goals, and why it might be helpful to whoever is reading this documentation. Keep it brief, but specific.
Features
This can be a list of features or just a description of what this project does / what can be done with it. I prefer presenting information in a bullet or numbered list as it improves the ability to scan through and gather information quickly. Short, specific pieces of information are much easier to digest.
Running The Project
If I were to find your project and want to run it locally myself, how would I do that? Be sure to include steps like cd into the project directory, run npm install(if dependencies are needed), and any other considerations for getting the project to run correctly on a local machine (CI requirements, Bash/Zsh, etc).
* ALWAYS add a live link if there is one so those checking out your work can see it up and running easily.
Example for this section:
Dependencies
Listing other peoples work that your project relies on is not only in good taste it helps show what your project is built on and adds insight to compatibility/integration with outside projects.
Dependency lists can also help others see what tech you are familiar with. If you are hunting for a new job listing out the cool new tech stuff you used in a project can make it stand out a bit more.
This too is usually a list and I prefer to make each dependency a link directing the reader to more information on that package or additional project.
3. Optional Additions
In addition to these basics it can be helpful to add other things in when applicable. A few of these include
- ToDo List — Features that will be added
- Contributors — List of those who contributed, if not a solo project
- Ways to contribute — How can others contribute?
ToDo List
Another approach to the features section is to list all the features you want or will be adding and check them off as you go. This is especially helpful on open source projects as people can quickly see if a desired feature is already on the ToDo list and avoid putting in a duplicate request. They can then come back and check progress (if you update your documentation!!).
Another consideration for the ToDo section could be prompting those using your code on how to report bugs or submit ideas for features. It is common to use Github Issues as a way to create, track, manage, and give status updates on features or bugs.
Note: reporting security vulnerabilities is usually handled more directly and NOT through public issues. It might be a good idea to offer a way for users to send these in through email or another private way.
If you’re not familiar with Github Issues (milestones, labels, etc.) the following article has the info you need!
Contributors
It’s always a good idea to list and link to the profile or personal site of any contributors. It’s not just the nice thing to do, it will help drive others to contribute to your project.
Ways To Contribute
Interested in having others add to your project? Tell them how! Most Github based repos people can simply fork, add to the project locally, and then put in a PR to your project which you can review and merge if you desire.
These instructions should be specific and include what types of PRs you’re looking for, how often you review them, code styling/formatting guide if applicable, etc…
Following these guidelines will hopefully set you on the path to writing better, more clean READMEs. The main point is to put forth an effort, making sure those who want to use your code can use it effectively. Happy coding!
Special thanks to Jim Medlock for lending his editorial eyes!
Did I miss something? Have your own documentation conventions? Let me know in the comments!
