/readme_refresh_day

README Refresh Day

Orientation

These are the goals and agenda for Immersion 2015 README Refresh day.

This is a @3 hour session with all front- and back-end developers at the CFPB.

By the end, several of our READMEs will be improved, better positioning CFPB team members, and members of the public, to use and contribute to our software.

You'll apply the lessons learned and empathy gained during this session to your future work at the CFPB.

https://twitter.com/kelseyhightower/status/543151215429701632

Know this: we are taking advantage of this unique opportunity to have 10+ new sets of eyes on our projects!

We will

  1. Review what constitutes a good README
  2. Review examples, good and bad
  3. Break into groups
  4. Get it done
  5. Reconvene and go over the highlight reel
  6. Be patient when things go off the rails
  7. Be kind... assume the best.
  8. Be delighted by surprises

Dependencies

  1. 35 (?) devs
  2. Laptops, github credentials
  3. Coffee, tea, bagels, etc
  4. Enough space for teams to work
  5. Wifi
  6. Screen and projector, Mac connector
  7. 7 (?) READMEs for improvement, with 5 more as backups if needed. We'll want printouts with git URLs so people can take them. Printouts should also have this README URL, so people can consult for instructions
  8. Overall session scribe
  9. Audio recording equipment

Instructions

Getting started (30-40 min)

  1. Orientation (10 min)
  2. What makes a good README? Look at our template; look at good/bad examples (15 min)
  3. Introduce our volunteers (5 min)
  4. Break into groups (5min). Each group must have
  5. at least one new fellow
  6. NOTE: we're optimizing for fresh eyes
  7. Go around the room by number

Group work (2h)

Each group will then

  1. Find a space, either in the conference room or in 10th floor project rooms / open space
  2. Designate a primary author for the changes. This person will coordinate everyone's input and submit the pull request with all suggestions
  3. Everyone in the group will fork the repo and clone it onto their mac
  4. Group members will then work through the README, trying to get the software running on their Mac, either in a VM or locally
  5. Group members will note missing or inaccurate info, improvements, etc.
  6. Group members will use this process to
  7. improve the README
  8. potentially change the software itself, including adding automation scripts, etc
  9. potentially file enhancement requests in the repo's issue tracker
  10. The primary author must push the changes to their own fork (for demo purposes)
  11. If you're ready, submit a pull request
  12. If you have no suggestions and the README is perfect, submit an issue to that repo indicating you reviewed it and it gets a thumbs up. Extra points for selfies.

NOTE: don't submit pull requests to public repos that contain internal URLs

If you finish early

You have options

  1. Get another README from the organizers and repeat above; or
  2. As a group, write about this process, what you learned or how you improved the README/software, which will serve as starter material for the article we publish on http://cfpb.github.io

Highlight reel (45 min)

Each group gets 5 or so minutes to talk about

  1. their favorite changes
  2. delights / surprises

Post-session expectations

  1. For each project, the group submits a Pull Request
  2. Any other improvements to the software can also be submitted
  3. Any suggested improvements, not completed during the session, should be added as issues to the repo's issue tracker
  4. Working with the session scribe, I'd like to turn this process, and what we learn during it, into an article for http://cfpb.github.io

Session scribe responsibilities

The overall session scribe actively listens and documents during the everyone-together portions of the session. Capturing the discussion is critical for a proper post-session write-up on cfpb.github.io

Lessons learned

  1. Allot at least three hours of dedicated time for your README Refresh Day. We felt rushed and could’ve used another 30-60 minutes
  2. Have enough READMEs preselected that teams can move on to another if they finish the first.
  3. Teams should pick another README if they start to work on a README and realize they are unable to continue. For example, a team might realize that the README they selected requires some specific knowledge that they don’t possess. In these cases, it’s better to switch to a README they can quickly improve in the time allotted, rather than spend a lot of time trying to learn the prerequisite knowledge.
  4. When teams broke into small groups and went to separate rooms, we used a dedicated chat room to ask and answer questions, paste links, etc.