Writing good readme-files
Code should be usable and reproducible by other researchers. That means that you have to include at least a minimal documentation.
A readme-file doesn't need to explain every detail of your software, but it should give the reader concise information about:
- What is this code about? What does it do? Why would you need it?
- How do you use it?
- How do you develop it?
Nowadays it is standard practise to write readmes in the Markdown format. The next chapter is an example-structure for a readme that you can use as a scaffold for your project.
Example Structure
Title of the software
Describe the essence of your software/library/code/snippet/data/whatever in one short sentence.
Status (optional)
If your software is not yet ready for other users or old and deprecated - add a status chapter and make this clear.
About
Describe what this software is. What it is like, what it is not like. Why is it useful. A picture would be cool. If there is an online-demonstration, you can put a link to that demo here.
Related work (optional)
List similar projects or software and explain how yours is different.
Installation
How do I get started if I want to use the tool? What are the prerequisites? How to install them?
Usage
Include a basic example which explains the basic functionality in a simple way. You may also include more complex examples
Development (optional)
If you want that other people are able to contribute to your project, you may need to explain how to set up a suitable development environment. Often times the development is very different than the usage.
Citation
If you publish a scientific library, you can ask the users to cite a specific paper if they use it. You can give them the BibTex code for example
Licence
A licence removes uncertainty around who may use the software how. Look at https://choosealicense.com/ to find a suitable licence.