Making repo descriptions short and clear

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 be 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.

18F GitHub repositories and descriptions, which are written below

The description for the repo domain-scan 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.

Screenshot of Description of Method Cards repository. Description: 'An initial collection of design methods, which includes general descriptions, how-tos, and how such methods can be put into practice for government projects

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 a project isn’t active, make that clear

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.

Add a website next to the description, when it exists

Next to the description of a repository, there's a spot to add a link to a website. You should always add a link to a website, if it exists.