Assignment 14

Due: 10:00 am, Mon 22 Oct

Read

We’ll be talking about good project READMEs next time in class. With your team, read at least two of the following:

• 18F.gov Guide to Making READMEs readable
• Starting an Open Source Project: Writing a README - part of a larger guide
• Template for a good README

Synthesize your thoughts on the recommendations, and come up with a list to share with the class next time.

READMEs on GitHub are written in Markdown, an enhanced style of plain text that can include some formatting. (Fun fact: this entire course website is written in Markdown.) If you’re not already a pro, read Mastering Markdown.

Do: spruce up your MP4 repo

MP4 is a public repository on GitHub, which means it is part of your professional software portfolio. Let’s take some steps to make it shine!

Better title

mini-project-4-interactive-visualization-myteam is a terrible name for a project repository, and “mini-project-4-interactive-visualization-myteam created by GitHub Classroom” is a worse description.

From 18F.gov’s open source guide:

Before naming a project, think ‘Is this easy to understand?’

To help users find and recognize your project, we recommend using descriptive names that describe what your project does. You should avoid acronyms and clever names/puns as those can make it hard to search for projects.

You should also do a quick search on the web for your project’s name to make sure that name isn’t already being used by other software or services, even if it’s used in a different space, as it can be confusing for new users.

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. Bad names might include the-unnamed-project-that-makes-it-easy-to-build-stuff, temp-latte, or guidestar.

Within the context of GitHub, the name of your project will always be placed alongside its organizational owner’s name. So it’s unnecessary to combine the two: instead of naming a project software-design-foo, you can simply name it foo.

Exercise: Edit your default repository name (under “Settings”) and description to better represent the theme of your project. If you want to run your thoughts by course staff, all the better.

Better README

It should be clear from your readings that every project should have a README file explaining what it does, how to run it, etc. On GitHub in particular, this is your project’s landing page and the first impression people will have of your work.

Exercise: Put what you read into practice by starting or improving your project’s README.md.

You are not yet done with your mini-project and thus may not be able to complete every section of the README, but we’d like you to post your first draft.