eeb C177

Week 5- Start your project with a README.md

27 Apr 2019

Goals:

Setting up the Term Project GitHub Repository and Readme

Since forming groups and finalizing projects in class (Week5 Monday), you have undoubtedly been thinking a lot about your Term Project. Many of you might be uncertain of how to proceed because you are still learning to program.
Fear not, you will learn a lot more in class and we will help you find out what you need to do in order to have a successful project.

This week in discussion you are going to think about the Term Projects at the broadest possible level – this is also probably the most important level. You need justify why you are making your project, and map out the steps needed to make your code (e.g. a flow chart of what needs to happen).

In the end it comes down to this, in order for people to effectively use your program they need to understand what it does, why it is useful for them, and how it works.

Your Term Project will live on GitHub and be available to anyone. Programs on GitHub live in repositories, and these repositories contain Readme.md files.

What is a README.md file?

Readme files are the advertisements and in many cases the manuals for programs. is a text file that introduces and explains a project. It contains information that is commonly required to understand what the project is about.

Suggestions for a good README

Every project is different, so consider which of these sections apply to your project. The sections used in the template are suggestions for most open source projects Readme files typically tell potential users:

  1. The name of the program
    Choose a self-explaining name for your project.

  2. The authors of the programs
    Name of students in your group

  3. The purpose for writing the program
    Let people know what your program can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. Also, depending on what you are making, it can be a good idea to include screenshots or images. Remember your favorite animal repository!!

  4. What they need to have installed to run the program
    However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Do they need R packages? Python Libraries?

  5. How to actually use the program
    The commands to run, how to access the help menu, etc. Show the expected output if you can. It’s helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.

In summary, you want your Readme to attract potential users, then convince them that you program is awesome, and show them how to use it.

Here are some example of Nice README files in github:

Today in class, you will generate the repository for your class project, and you will begin to write your Readme. It is likely that you will make a lot of changes and additions to the Readme over the next 5 weeks. If you do not modify this document I will be concerned that you are not making progress on your project.

By the end of the day, you will have a repository with a name, the names of the authors, and an introduction that introduces the project, justifies its existence, and provides a rough description of the steps required to take an input dataset and transform it to the desired output dataset.
If you don’t know where to start, play around on GitHub, and search for program repos that you can use as a template.

Note: Your introduction will contain citations. You will cite relevant programs or studies related to your project. You are free to use any citation style, but Chicago is a pretty standard format.

In-lab-questions

Appart from your README file you have to answer some questions related to your project. Please get the questions from this repostiory. Also, try to answer some of the questions (question one at least) during this discussion. This information will help you to write your README file faster.

How do I even start ???

There is not a single way you can start doing a README file but here are some usefule tips from things you have alredy done in previous discussion sections.

Tweet