Writing a Great Project README

What’s the first thing you do when on-boarding a developer onto your project?

Do you need to spend time digging for notes on how to get the project checked out locally, the tools to install and use, and commands to run? Do you have to provide URLs to the various server environments, steps to run a migration, or something as simple as the underlying system base or architecture? Do you waste time digging through emails for each person on your team?

The first thing you should be doing is say “Hi” and provide the developer with the project README. A not-too-long, but just long enough, yet concise overview of the project, so they can orient themselves.

NOTE: A README is a great reference as well. So 6 months in, you can go back and grab a tidbit, you might have forgotten while in the fray.

Getting Started

In my projects, the very first thing I do is to create a blank git repository, and then immediately proceed with Pull Request #1 – the start of the project README.md file.

So…what goes into a great README?

A great README should provide enough detail to get people up and running without being a giant tome to read. Remember, documentation is only useful if people actually read it. If it’s too long or boring or out-of-date, it will be ignored. With that, let’s get straight to the point. Vary this for your case, but, this is what I like to start with as the base set of topics to document.

  • Project Name – A short summary of the reason and goal of the project so the team immediately understands what the goal is. One or two sentences max.
  • System Summary – The underlying stack in use, backend and frontend tools in use, etc.
  • Project URLs –  Links to SCM repository, ticket tracking system, local VM URL, CI tool and of course links to new (and current if relevant) DEV, QA, UAT and PROD servers.
  • Team Communication – List here the tools your team uses to keep in touch. HipChat, Skype, etc.
  • Development Targets – List here your target platforms or browsers so developers know their end result target platforms or devices.
  • Development Prerequisites –  Any underlying needs such as Mac OS X, or XCode, or Windows, virtual machines, or any other tools your project might depend on. We are all standing on the shoulders of giants.
  • On-boarding – The steps needed for a developer to get their local environment setup. Perhaps including SCM instructions. Getting the project checked out and running locally on their first day. It can often be best to script as much of this as possible. I promise you, it’s far easier to say… hey… go run bootstrap.sh. Done!
  • Day to Day Development – This is where all the magic is happening. Day to day processes or any special tasks should be laid out. Your git workflow, vm commands, drush commands, UI toolkit needs, CSS preprocessing, deployment needs, ticket tracking requirements, etc.
  • Migration – Is there a migration? Does it need to be used locally for any reason. Describe any potential needs here.
  • Testing – Are there testing scripts? Any special QA needs? Document the processes here.
  • Offboarding (Uninstalling) – Once the project is complete or someone on your team is jumping to a different project are there any special needs to uninstalling anything for this project? Sometimes not needed, sometimes needed. It can be best to script this as well.
  • Troubleshooting – Nothing is perfect… there will be issues. Stay calm and document any potential known caveats that might come up. Describe how to handle the ones that are known. Update the README when these are solved or if new ones come up.

These are the basics I like to cover in our project READMEs. This can easily be expanded and adapted to your projects.

Are there any other topics on your projects that you find you have to dig for or describe for each new team member involved? Add it to your README as you go along.

Keep it updated and at the root of your codebase! It only takes a few minutes here and there to jot down a note as it becomes relevant and will save you a lot of time in the long run. It also instills the feeling of a well-organized project to those joining in easing the transition and lowering the barrier to entry.

Are there any other topics you always put in your README? Looking forward to your comments below.

Resources and Further Reading

One Response to “Writing a Great Project README”

  1. Ellie Strejlau

    Great post, Matt! I really like this approach to writing README files and will be using it in the future. 🙂

    I’d like to add that if you ever have trouble composing markdown files or if you’d like to see the output before you commit it, you can download a markdown editor like MacDown (Mac OS X / free; http://macdown.uranusjr.com/). There are also plugins for text editors like Sublime Text that help with writing markdown, such as MarkdownEditing, which can be installed via Package Control (https://sublime.wbond.net/installation). If you’d rather not download anything at all, you can edit and view markdown files on online editors such as Dillinger.io (http://dillinger.io/) and StackEdit (https://stackedit.io/editor).


Leave a Reply