Writing READMEs that will make future you happy

March 6, 2017

Most of us struggle to decide what to include when documenting our projects, but some research can make the process a lot easier.

Are you:

I've also felt that sinking "staring at an empty README file" feeling so I identified what made getting started easier. Enjoy!

What makes a README?
Let's not sweat the Markdown, the flashy demos and screenshots, or the badges just yet. Good READMEs are more about clear writing - clearly stating what problem your program solves, it's use, and (if you're looking for contributors) ways of getting folks familiar and able to jump on board - than they are about all the flashy "extras". You may have used outlines to organize your thoughts and test the strength of your thesis when writing. Sketching out an outline also helps get the “blank page” fears out of the way, so let’s begin to fill this in with the information your documentation should always include.

Core Components
You should always include an introduction to the project (and the problem it solves), list any programs or modules your user will need to have as requirements, and installation instructions. Most READMEs include troubleshooting information and a call to action if the author is hoping for contributors. Remember your goal: You are providing information to help someone use or improve your code. What do they need?

screenshot of a README with the Introduction, Requirements, and Installation headings circled in red with the label 'All the information you need for a simple program'
A README that includes all the information needed to run a simple program.

The Selfish REA(D)ME (a la The Selfish Gene/Meme)
In the beginning, most projects have one contributor, and I learned that the READMEs that other folks found the most helpful were the ones that I had written not for an imagined future user, but for my future self. If I were to rediscover this project three years from now, what would help me start using it again? What would help me make my first commit after being away from the code (and the problem it solves) for so long? These questions guide the first draft of every README I write.

Putting your best foot forward
Even if you have been writing and testing your program alone in your living room, you recognize that writing code is more exciting when it's used and appreciated by others. It's now time to step outside your own head, put your "user hat" on, and think about why someone might want to use your project. What will they wonder when they stumble on your README? I usually have a friend read my first draft over and ask them what they learned about my project, a technique called "say back" among writers. If they didn't glean what I'd hoped, I adjust my emphasis.

You can take the "have a friend read it" approach one step further by attending sprints (project-centered work parties) or "docathons" (hackathons focused on documentation, click here for information on one that took place recently, including presentation slides and a slack channel) that support other open source projects. I've found that reviewing other projects' documentation by following their instructions for contributing will teach you a lot about what your own first-time contributors will benefit from! "Taking a walk in your contributors' shoes" is an essential step toward becoming a compassionate documentation writer.

If you can throw in a little humor, most readers will appreciate it provided all the important elements of the README are still easy to find. This version of the game "bottles and kegs" was a project I stumbled upon months ago and it still makes me chuckle.

As you become more comfortable with your writing, you can investigate using visuals to inform your reader about your project.
There are many options:

Documentation as a thinking aid
Get ready to write awesome docs by practicing clear thinking while you code. Especially as I learn how to scope projects, I find that writing some form of documentation at every stage of the project helps me break functions into tasks and keep the "big picture" goals of the project in sight.
For me, there are two ways to do this:
  1. At the beginning of a project, create comments for each action your code needs to take. You'll likely find that you have just described each of the functions you will need.
  2. As you write each function, give yourself a docstring describing what the function does, including its inputs and outputs.
These comments are an important step for me as I organize my thinking. Most folks remove these comments from their final product, but future viewers always welcome docstrings (including future you!).

If you're using Python, docstrings are written in the first line of a function, class, or method and enclosed in triple quotations, like this: """ Description of function here """. Other languages, including Java & Swift, support docstrings as well (see Wikipedia for more examples). Documenting individual functions not only allowed me to organize my thinking while I was planning the project, but if I put off my documentation until I was finished, it prevented my complete confusion when looking back. It's much easier to summarize something when you have an "outline" of docstrings in front of you!

Doc Generation
Generating your docs from comments and docstrings is a powerful way to jumpstart your documentation. Many languages and frameworks have their own tools available, or your can explore something more generic like Gitbook.

Tools and Resources
The Write the Docs Documentation on Writing Documentation (say that four times fast!) is a spirited guide that walks you through the paces with an emphasis on the "why" of each step. Definitely worth a read (and probably a follow on the twitters if you do that).

The Drupal project has its own guidelines, as do most larger open source projects. Reading and getting a sense of what has worked for others (and thinking about what makes sense for you!) is the best way to make informed decisions about what information will be most helpful for your project. The headings I listed--Introduction, Requirements, & Installation--are considered the “bare bones.”.

Grip is a tool that allows you to view your documentation locally. If you find yourself committing to Github in order to view and then make additional changes to your Markdown, this is going to be a real time saver (and result in a much cleaner commit history)!

screenshot of two commits, the first adding an image and a second to resize it because image was not viewed locally before committing
Don't you hate when you need to make a second, third, or fourth commit
as you tinker with the size of an image? Never again!

The beautiful-docs repo has its own list of excellent docs and resources to aid doc creation.

Rich Bowen's call for better docs critiques examples of some of the best documenation out there, and it is definitely worth a read. He is involved with the Apache Software foundation, which has some of the best documentation I've seen (here's an example).

Best of luck with the communication side of your programmin'. If you remember to write the documentation your future self would want to have and clear your head by spending some time experimenting with starting documentation early in your projects, you'll be well on your way and ready for all those bell-and-whistle resources I included here.

Time to go out into the world and write some fab docs!