Building applications across a distributed team with multiple clients can be challenging because we all have different operating systems, chipsets, or application versions. That means it can take a lot of time to set up an application, taking time away from time we could spend building features or updating a project.
One of the first places we can focus on to help improve a developer's experience with an application is in the README documentation, as frequently, this is our first interaction with a project.
Below, we'll walk through an efficient framework and examples of the questions I think of when reviewing and maintaining a README.
What’s a README?
README files are documents typically included in software projects, particularly open-source projects. They serve as an introduction, providing critical information to potential users, contributors, and maintainers. A well-written README should include the following:
- Complete build instructions for the application.
- An overview of the project and what the application does.
- Information on installing and using the project.
- Any project-specific custom features.
README files can be in any format, but they are typically plain text files written in Markdown or other lightweight markup languages. Markdown is a simple and widely-used syntax for formatting text that is easy to read and write. We like it because it provides a preview viewing of a README, which is typical of what you see at the bottom of a repo in GitHub. This preview view is often more visually appealing and easier to read than the raw Markdown version.
An effective README is much more than just a standard document, though. It's a living document that changes as the application evolves and requires adjustments and updates. For example, when the project's version of a dependency changes, so does the documentation.
What Makes Up a Well-Written README?
Accessibility
It's important to use explicit language without making assumptions about what a developer might or might not know. Every aspect of the application should be communicated simply and precisely. When updating the document, take the time to write complete commands in the order required to be successful, prioritizing working towards simple, approachable word choices, avoiding jargon and abbreviations, and taking the time to thoroughly write what tasks are expected. While the goal is not to treat the reader of the README as an inexperienced developer, you'll want to make this document as plug-and-play as possible.
Login instructions
The username and password for varying sign-in levels should not be assumed and outside of specific Open Source projects should these credentials not be kept in the README. Whether they are stored in LastPass or need to be created, please spell this out for the developer.
Other Documentation
Finding the balance between too much information and just enough can be challenging. The other documentation section is a great spot for that Wiki or GitHub gist containing the setup instructions that might be important but not primary to your team.
My Favorite README Example
One of the best examples I have used came through an open-source project, Ruby for Good, a fantastic community of developers who build production applications for organizations in need. My favorite README with Ruby for Good is the CASA README. The CASA application helps track the interaction of people within the foster care system.
This README introduces the project and provides essential information to potential users, contributors, and maintainers, all of whom can come from all levels of coding experience and varying levels of English proficiency.
I encourage you to read it, but as an overview, here are some areas where this document excels.
Index
An index of each section of the README allows the reader to choose their own adventure, skip unneeded sections if desired, or fully take in the README. The index provides options for the person who wants to skip to the 'meat' of the project and the individual who desires a total understanding of the application. As an open-source project, this application can have a developer who has never worked on production projects and, on the other end of the experience level, folks with oceans of experience.
About
An about section helps developers understand what this application does in simple terms.
Applications can sometimes have specific language around HIPPA or other information regulations and terms. This section gives us a window into a person's questions outside of what the schema provides. As a person who works on multiple projects, I sincerely appreciate this section.
Process
A straightforward, step-by-step process for building the application that makes no assumptions about your understanding of technical jargon.
While not specific to every workplace or project, this README is one that we can use as a test for our documentation.
How Does This Help Our Clients?
We have applied many of the above suggestions to minimize setup time and help new staff members understand this project. For example, we recently onboarded a new staff member to a project we have maintained for over two years. Because our documentation was clear and updated, her setup time was reduced from a week to a few days. This saved client billing time and allowed a new staff person to be onboarded and work on solutions instead of spending another day attempting to locally build the application.
Taking a few minutes to be diligent with your README documentation can bring incredible value to a project. From reducing start-up stress to improving the maintainability of your application, a healthy and updated README is not only a best practice - but a huge relief!
🎙️You might also enjoy listening to Maintainable Podcast's Episode with Marit van Dijk, in which she and Robby Russell (CEO of Planet Argon) discuss some README best practices. (Convo begins around 2:45.)