Shea Furey-King

I am currently on a mission to learn more about open source and begin contributing. In this post, I talk a little about how READMEs are important to open source projects.

*An earlier version of this post was named “I Went to a Workathon and All I Coded Was a README.”

Backstory

For those of you who do not know, there is a movement gaining momentum in the NYC tech scene. Developers, designers and tech enthusiasts alike have been meeting and plotting ways to revolutionize how technologists interact with and build solutions for government, news media, schools, and other civic services. Many of these institutions are in dire need of new perspectives. This past weekend, a group of those technically-inclined met to work from 10am-5pm on three feature projects at ThoughtWorks. The group is an inspiring collective of people and I encourage you to learn more about Make A Diff here.

I went with the intention of contributing to a good cause, but mainly I went with the thought that I would contribute code to an open source project for the first time. I am ready! After a year of intense studying in coding and teaching myself core concepts and OOP, I was ready to submit my first official pull request to not just any open source project, but one that was truly a good cause. And then I arrived at the event.

I joined a small group working on a project called Civic Tech Projects, a platform that would present a collection of tech projects with a civic focus looking for contributors. When we divided the project into chunks, several people volunteered to start on the frontend and workflow, leaving copy which I offered to do with another developer.

Though I originally set out work on another set of issues and skills, it was a great opportunity to think in depth about copy, READMEs, how to make them, and why they are important to open source projects. Below are some of the lessons I learned.

Elements of a Successful README

First of all, what is a README.md? In a GitHub repository, it is a markdown file on the main page of the repo* and the first file a person will/should read. It gives a brief overview of the project and describes how some of the main features work. It is a file solely for the developer; it does not interact with the codebase. In order to write a meaningful README, you need to know a couple key things about the project:

1. What is the goal of the project?
2. How does the project work?
3. What is the minimum information a developer needs in order to get started?
4. How can a developer contribute?
5. How can someone learn more about the project?

Goal

The goal should be incorporated into the first few lines of the README. It serves as an introduction and tells a contributor what this project can be used for.

How does the project work?

You need to know the main functions of the project. What makes this project unique and how is it coded? If you don’t know the answer to this, ask the developer to name the libraries and major functions in the project. Also realize that how the project works now might change based on future refactoring. And that’s ok!

Minimum Information

While you have to give a new contributor some information to start, you don’t need to tell them everything. In fact, it is probably best if you do not overwhelm them with too much information. Stick to the most important features.

How to Contribute

This part is really important. This is where you will give installation instructions, tell contributors your expectations on how they interact with the repository and point to important issues. You might even include contact information if you want them to touch base before making large-scale contributions.

More Information

Remember all that extra information you cut out of the README? You should still share it will potential contributors. Give them links to background info, set up another markdown file with detailed instructions on contributing, or list similar projects.

README’s do not have to be organized according to the bullet points above, but most successful repos cover each of these key questions in some way.

*Not all GitHub repositories have README files, but that would be another blog post.

Quick GitHub Markup Cheatsheet

After developing the content, you need to format in a readable format. Here are a few common markup tags to help you get started:

For main headers or H1, use # in front of the text.

# My Main Header

For secondary headers or H2, use ## in front of the text.

## My Secondary Header

To make an unordered list, use * in front of each list item. You’ll need a space in between the * and first word.

* Apples

* Bananas

* Oranges

To hyperlink, use [] around the text that will be hyperlinked and follow it with the url wrapped in ().

[follow me on twitter!](https://twitter.com/shea_fk)

Summary: READMEs Are Like Gatekeepers

A GitHub repository without a clear README is like a book without a cover and summary. No matter how amazing the core content is, a potential contributor might never look at your work if they are missing the initial context.

If you attend a hackathon, workathon, or join any type of group project and are delegated copy or documentation tasks, give it love! You are the gatekeeper welcoming or dissuading potential open source contributors; the project’s success does in part depend on your work.

Stumble upon any attractive README’s recently? Send them my way! I am always looking for better ways to write documentation.

Special thanks to ThoughtWorks and all of the Make-A-Diff organizers—especially Ben of The Practical Dev for encouraging me to write a blog post about the day. Learn more about Civic Tech Projects here.