3  README file

Author

Paschalis Agapitos

3.1 What is a README file and how to write a good one?

A README file is basically a text file that is used as an introduction to your project. In addition to that, someone might want to explain, share information required to understand what the project is about.

Moreover, a README file might contain some information on how to install and use the project.

3.2 Conventions to write a good README file

A README file is the first thing someone sees when they access the repository, thus a README file should be as good as the project itself. For this reason, there are some elements that should be included in a good README:

  • Project Title: The title name of your project

  • Description: Description of the main purpose of your project. If any, someone could include the research question and consequently the scope of the project itself.

  • Features: If the project has multiple features, this is the place where someone should list them; including screenshots is always useful and works as an eye-catcher.

  • How to use: This is the manual of your project. More specifically, here you should write step-by-step all the instruction on how to install and use your project, plus any software requirements or dependencies.

  • Technologies: List all the technologies and/or frameworks you used and what purpose they serve in your project.

  • Collaborators: If others have contributed to your project in any way, it is important to give them credit for their work. Write your team members’ or collaborators’ names here along with a link to their GitHub profile.

  • License: It’s also important to list a license on your README so other developers can understand what they can and cannot do with your project. You can use this guide to help you choose a license.

Bear in mind that your README should be brief but concise, detailed and up-to-date.

If there is anything wrong, please open an issue on GitHub or email f.pianzola@rug.nl