The most successful open source projects have informative and entertaining READMEs. There are badges, screenshots, animated walkthroughs, and getting started guides. Some even break it into separate documentation sites that match the sections in a README.
With a quick glance through one of these open source repo’s README file, you’re likely to have a complete grasp of the project. You’ll be able to access a summary of the purpose, who made it, why they created it, who it’s for, how to install it, and how to contribute.
It’s usually not the same as the crucial repositories inside of our organizations. It’s odd these often end up with outdated and empty READMEs despite being mission-critical components of a business.
Are OSS maintainers obsessive documentation fanatics? I don’t believe maintainers and contributors have a bizarre affinity for documentation.
They are passionate about creating software that helps others change the world. To get their project into the hands of the right users it takes some ‘marketing.’
When you dive into a new popular project, it’s clear someone took hours of time to document it so more people could use and contribute to it.
After volunteering hundreds of hours of work, it makes sense they’d want it to be as easy as possible for people to understand, use, and contribute. Without a thoughtful README, potential users would likely not discover the repo and miss out on the great functionality.
Does this mean every repository in your company should have an equally robust README? One with thousands of words, build stats badges, and GIF walkthroughs?
No, your team’s codebase is different from open source. There are only a few potential contributors to your repos, you’re likely all in the same office, and there are opportunities for people to ask questions if they get stuck.
It’s likely most of the code only applies to your business’s use case and despite an empty README your team will still use and contribute to the project.
It makes the README an afterthought for most internal repos. Something on the list of things to do between sprints. They’re usually filled with vague bits of information added when the repo was created long ago.
Many dev teams think since they’re not trying to market the repo to the world there’s no audience at all for an internal README.
So why bother with spending time on your READMEs? Fundamentally, having a useful README makes it easier for your team to push cleaner code.
Everyone on a development team benefits from a project with a clearly defined README. New hires will be able to quickly get set up contributing code that matches the team’s standards. Overall, the whole team benefits from having more people know how to run and fix the project.
Here’s to small changes in your READMEs
Most internal repositories contain the bare minimum already, such as a single sentence describing its usage. While there might be a lot that could be added, it’s difficult to know from the beginning what’s vital to include for your company and the project. Don’t expect to write pages for every README overnight.
To start making improvements, there’s an easy way to set the foundation that gets the team to begin the process. Pick your three most important repositories and the three most essential things for your team to know. For example, how to run, how to test, and why critical decisions were made.
From that foundation, you can encourage everyone on your team to work towards incremental changes to the README whenever possible. Adding a small comment during code reviews of relevant pull requests will improve the overall quality of your READMEs.
