writingGoodReadmes.md

# 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]( https://en.wikipedia.org/wiki/Markdown ).
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.


## External links


 * https://gist.github.com/PurpleBooth/109311bb0361f32d87a2
 * https://dotdev.co/how-to-write-a-readme-that-rocks/
 *
	# 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]( https://en.wikipedia.org/wiki/Markdown ).
	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.


	## External links


	* https://gist.github.com/PurpleBooth/109311bb0361f32d87a2
	* https://dotdev.co/how-to-write-a-readme-that-rocks/
	*