- {% if site.logourl != null %}
- 
- {% endif %}
-
-
- {{ site.name }}
-
-
- {% include sidebar.html %}
-
-
-
-
-
-
- {% include footer.html%}
-
- 
-
- If your project is active, does your description:
- -If your project is no longer active, does your description:
- -Does your README answer the following questions:
- -Are your issues:
- -
-
- This guide helps people document code repositories so that they're easy to use and understand. In each section, we outline our strategies for making sure that our code repositories are clear, accessible, and user-friendly.
- -It’s important to make sure our documentation is clear both for internal and external audiences. As our team expands, we want our new employees to easily find and use our existing codebases.
- -It's also really important if we want to make outside contributors feel welcome or have outside organizations fork and use our code. (And we do!) Explaining what a project is, why it's important, and how people can help ensures that people can fork and adapt our projects.
- -This guide also contains a checklist we created that helps ensure our repos are clear, accessible, and user-friendly. Some terminology used may be GitHub-specific, but the concepts are applicable regardless of your version control system or platform.
- -We’re sharing it because it we think it’s helpful for lots of organizations, including our own. We know that many of our repos don’t conform to this exact style. By articulating a specific style, we hope this document will also help us improve our own practices.
- -We created this guide for reference on an as-needed basis. It’s here when you’re wondering how to describe a repo, for instance, or when you’re wondering how to create a friendly, informational tone when writing issues for users.
- -To this end, we’ve structured the guide into descriptively named sections. Browse our table of contents to find the topic you’re looking for.
- -Most importantly, we encourage you to make a copy of this document and adapt it to your organizational needs. This guide is just that: a guide. It’s not meant to provide the final opinion on any of the topics discussed. If a certain section isn’t relevant to you and your team, delete it. And if you feel the guide is missing a section, by all means, add it. This guide is yours to use, and we trust you’ll update it in the ways that best suit you.
- -
-
- Every repo contains a README, which is a document that is intended to explain, at first glance, what a project does and how to install or test the code.
- -READMEs are really important because they’re the first item a user will see when encountering your code. Creating a readable README ensures that your co-workers and the public will be able to understand the intention of your program, install the software, and fork and adapt your projects.
- -We find it helpful to think of the README as a guide to your code or project. It’s often helpful to create sections in the README for users to learn about the project. We recommend the following sections.
- -This should answer a short list of basic questions:
- -You likely have the answer to many of these questions in your head and have discussed them with your team. It's helpful to write them down for people who find your repository. Not only will it be easier for developers to know how to fork the project or become involved with the project, but it will be easy for non-coders to understand what the code is designed to do, and how they, too, can become involved.
- -Example: The README for 18F’s Midas project starts out by answering the questions:
- -This should answer the question: How do I get this project to work on my machine? How can I develop for this project? We find it works really well if you follow a two-step approach to develop the content for this section: first, help someone setup the site who has never done it before, and then write down the exact instructions. Next, ask someone to follow those instructions and see if you’ve missed anything.
- -Important: If relevant code changes, it’s important to test to ensure these instructions continue to work. We also recommend separating the sections for using a project versus developing for it. (More detailed instructions are located in our guidelines for writing documentation for users, contributors, and developers.)
- -Example: The README for 18F’s homepage contains detailed instructions for developing the site and deploying the site.
- -Example: The README for Midas contains a link to installation instructions for developers.
- -We explicitly welcome outside contributors. It’s important to explicitly state how they can help and what they can help with. This part of the website should answer the question: How can outside contributors become involved? We include a CONTRIBUTING.md file in each repo, which outlines the following:
- -Example: The README for Midas contains a section called “How you can help.” What we really like about this section is that it doesn’t assume helpers are developers and lists ways for lots of different people to contribute. (Our guide to welcoming non-coders to hackathons also contains many suggestions for ways to involve people with different skillsets.)
- -We also recommend reading Midas’ Contributor’s Guide, which orients new dev contributors and tells them the best ways to communicate with Midas’ dev team.
- -This part of the repo should answer the question: What is the license for this project? All 18F projects are developed in the international public domain whenever possible and contain a LICENSE.md document, as well as a paragraph at the end of each README which contains information about the public domain. We post this information in the README, so that users know the code can be adapted and reused, and so they can easily see this information instead of going to a second site.
- -This part of the repo should make it easy for users to get in touch with the team developing the project. This is also where you should list any listservs, chat programs, or social media groups that have been created to keep contributors informed.
- -Any other information that you’d like to share with users can go in the Wiki section of your repository.
- -
-
- We recommend using descriptive names and avoid acronyms. It’s also important to check with your communications team before naming a project so that it can be cleared, if need be.
- -For example, if you were creating a template your coworkers could use to create guides, a good name for the repo might be guides-template. A bad name might be the-unnamed-project-that-makes-it-easy-to-build-stuff.
- -
-
- Some of our teammates recommend turning off a repo's Wiki unless you have a proactive use for it. But there are many ways to use a Wiki and use it well.
- -If you’re using GitHub, you can enable a wiki on every GitHub repo by going to its settings and checking the ‘Wikis’ box under ‘Features.’
- -
What does this get you? Tons! You can now put all the great information that would have made your README way too long and complicated into separate, clear pages. For example, the 18f.gsa.gov team uses the wiki for all their “how to do this” work, and catalogues items like decisions on which blogging tags to use across our sites.
- -
Another really great use for the wiki is to house your product roadmap and user research goals. 18F’s Michelle Hertzfeld is a huge proponent of keeping these documents in the repo with the codebase so they’re easy to find, share and get feedback on.
- -Speaking of user research, some of our project teams also like to keep their research process and findings in the repo along with the code. This helps keep all project documentation together in one place and also makes sure that we’re not only building in the open, but also researching in the open. This way, team members ,and anyone else who is interested, can track the research that went into project decisions.
- -Naturally, this does not include posting confidential interviews with people or anything else that should not be shared. What it includes are things like: -* Research plans -* Interview scripts -* Summarized research findings
- -One way to do this is to create an “orphan branch” to keep your research in. An orphan branch is a branch that you name that sits within the repo. Creating an orphan branch lets you have a completely different file structure from the rest of the repo in that branch, and you can put all of your research within that branch, as follows:
- -
-
- Tasks that need to be completed or discussed are added to repos as issues.
- -If you want outside contributors to help work on your project, it’s important to write clear issues that detail what people can work on. You can also use labels to distinguish issues and sort them into categories. For example, here are all of the open issues on the Midas project that are listed as questions.
- -It is particularly helpful to use the ‘Help Wanted’ label for tasks or questions you need help with. (Examples.) Why? There are other sites, like Govcode and Code for America’s Civic Tech Issue Finder, which surface issues that have been labeled ‘Help Wanted’ so people can jump in and help. You can also use the ‘Beginner Friendly’ label to specifically note tasks that are suitable for beginners.
- -When writing an issue, it is often helpful to craft it in terms of a user story because it frames the task in terms of a user need. User stories are framed as follows: “As an X, I want to do Y because Z.” Here is an example of an issue framed as a user story.
- -
-
- The description of a repo tells the public what is contained in the repo itself. If you have multiple repositories for the same project, it's better to describe what is contained in the repo itself instead of describing the project.
- -Repo descriptions should clear, concise, and descriptive. Descriptions are listed under each repository title on an organization’s GitHub page. Anyone who scans the GitHub page should be able to determine what a repo does, just by looking at the description.
- -For example, let's look at the description of some 18F projects.
- -
The description for the repo domain-side is "Scan domains for various web things, like HTTP/HTTPs configuration."
- -The description for the repo midas-open opportunities is "Digital Services Innovation Center's Open Opportunities on the Midas Platform."
- -And the description for the repo pulse is "How the .gov space is doing at best practices and federal requirements."
- -Each of these descriptions is clear and tells the user exactly what she or he will find when opening the repo.
- -
It’s sometimes hard to think of a complete description of the repo in one or two sentences. An easy way to come up with a good description is to think ‘How would I explain what this project does in one or two sentences to someone at a dinner party?’ Those are the sentences you want to write down as your repo description. Before you publish, it also helps to run your description by someone who doesn’t work on your team. Do they have any suggestions?
- -If your repo is not in active development, it’s helpful to let users know this so they don’t make contributions to a non-active repository. We suggest adding the word DEPRECATED before your repo description. Here is an example of a deprecated repo.
- -