Improving the new developer experience with a README Refresh Day

As part of our 2015 Technology and Innovation Fellowship, 11 new developers joined the CFPB’s Design and Development team. During the new fellows’ orientation, the entire development team took advantage of this fresh energy and perspective to ensure that documentation on some of our critical open source software was accurate. Specifically, we held a “README Refresh Day,” where small teams looked at seven README files on our GitHub repositories and submitted improvements and recommendations for future improvements.

The README Refresh Day helped us improve the quality of our open source software and its ability to be used and adopted by the general public. This effort effectively helps to pave the path for participation and collaboration, and helps to build a community around software. These are key tenets in open source software development, the presence of which helps to ensure software quality and success. The README Refresh Day also presented a number of added benefits: (1) It helped orient new developers to technical environments and processes, and (2) it helped to reinforce an important cultural value: Empathy – empathy for other developers, or anyone in the public who would want to understand our software products. The easier our software is to understand and develop, the faster and more effectively we can deliver value to the American public.

The Challenge

Collaborators on software projects are frequently encouraged to write good installation and usage documentation and keep that information up to date, but even on the strongest of teams, creating and maintaining correct, up-to-date documentation is a real challenge. The documentation often:

  1. Does not clearly define the problems the software attempts to solve
  2. Assumes a level of expertise on the part of users/contributors that is too high
  3. Omits key installation and configuration details
  4. Does not keep up with changes to the software and thus drifts out of accuracy (aka “documentation drift” or “documentation rot”)

Organizing the event

A small group of existing CFPB developers organized the event, including planning and event-day activities, documented at https://github.com/cfpb/readme_refresh_day. We scheduled it during the fellowship immersion period as an activity to bring new developers closer with existing developers, and also to provide all developers – veteran and newcomer – with an opportunity to explore software created by other CFPB project teams. This also provided veteran CFPB developers an exercise in humility and empathy, as they watched other developers attempt to install and work on software, which they had created previously, using just the README.

Outcomes

Our raw notes can be read at https://github.com/cfpb/readme_refresh_day.

During our three-hour session, 25 developers worked on software they had never seen before, using just the README. In the group intro discussion, our new developers contributed valuable insights into what constitutes a good README, and these suggestions will become part of our open source template. Our developers shined a light on out-of-date or completely missing instructions and assumptions made by previous authors. We also looked for missing or broken “badges,” such as Travis CI and Coveralls, and added or fixed those.

Additionally, it was an excellent opportunity for new fellows to get a hands-on introduction to some of CFPB’s open source software projects. If those developers who haven’t seen the software before couldn’t figure out how to install or use it from the README, they had the opportunity to dig into it (albeit briefly) and try to determine what might be missing from the README. At the end, even if they had no answers, at least they had a much better idea of the questions they needed to ask.

The session resulted in 14 pull requests to nine of our open source projects on GitHub, and 21 issues added to these repositories for questions, comments, or enhancement suggestions. We also came away with a humbling sense of the differences in README quality amongst our repositories, and we’ll use this learning to improve across the board.

If you want your developers to learn more about software with which they’re unfamiliar, develop empathy for new users, and improve the welcome mats to your projects, hold a README Refresh Day.

For an activity that requires only a day or two of planning, the results in both teamwork and software/documentation improvements are impressive.