We ask all students working on projects and theses with us to
- hand in their source code and
- provide a documentation for their project.
Source code (including the code architecture and comments) has to adhere to our developer guidelines. The project documentation consists of one or more a README.md files that cover the topics listed hereafter. Thus, copy this file's content to your project and use it as a template to write the documentation for your project.
Aside from using this template, also check out the following sources for examples and guidelines on how to write a good README.md for your project. Note that the exemplary projects do not follow this template completely (either because they were created by third-parties or before we consolidated all the information into this template). They are still good examples of high-quality README.md files.
- Example: news-please
- Article: How to write a good readme
- Article: A beginners guide to writing a good readme
Useful tools:
A short description of the project’s purpose and main functionality. What does the project do?
A short description of the project’s motivation. Why does the project exist, and which issues does it address?
What makes your project stand out? Include screenshots, code snippets, logos, etc.
Include very short code examples that show what the project does as concisely as possible. Developers should be able to figure out how your project solves their problem by looking at the code examples. Make sure the API you are showing off is intuitive, and that your code is short and concise. See the news-please project for example.
Provide step-by-step examples and descriptions of how to set up a development environment.
For small projects with a simple enough API, include the reference docs in this README. For medium-sized and larger projects, provide a link to the API reference docs.
Describe and show how to run the tests with code examples.
Include a step-by-step guide that enables others to use and extend your code for their projects. Whether this section is required and whether it should be part of the README.md or a separate file depends on your project. If the very short Code Examples from above comprehensively cover (despite being concise!) all the major functionality of your project already, this section can be omitted. If you think that users/developers will need more information than the brief code examples above to fully understand your code, this section is mandatory. If your project requires significant information on code reuse, place the information into a new .md file.
If you performed evaluations as part of your project, include your preliminary results that you also show in your final project presentation, e.g., precision, recall, F1 measure and/or figures highlighting what your project does. If applicable, briefly describe the dataset your created or used first before presenting the evaluated use cases and the results.
If you are about to complete your thesis, include the most important findings (precision/recall/F1 measure) and refer to the corresponding pages in your thesis document.
Include the project's license. Usually, we suggest MIT or Apache. Ask your supervisor. For example:
Licensed under the Apache License, Version 2.0 (the "License"); you may not use news-please except in compliance with the License. A copy of the License is included in the project, see the file LICENSE.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License
License of this readme-template (remove this once you replaced this readme-template with your own content)
This file itself is partially based on this file.