From 273eada6c769b2c6e1d0acd03ef97164f9fa6f6f Mon Sep 17 00:00:00 2001 From: Tom Theile Date: Mon, 11 Nov 2019 17:27:46 +0100 Subject: [PATCH] update README.md --- README.md | 8 +++++--- writingGoodReadmes.md | 42 +++++++++++++++++++++++++++--------------- 2 files changed, 32 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 75bf0ee..18bedbd 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # Good practices in scientific software development at the lab of digital and computational demography -This repository contains several guides on software development at the lab of digital and computational demography: +This repository contains several guides on software development at the lab of digital and computational demography. -[How to request and perform code reviews](HowToCodeReview.md) +This is work in progress, expect changes in the next weeks and months. I am happy to receive help, criticism -[Writing good readme-files](writingGoodReadmes.md) + * How to [request and perform code reviews](HowToCodeReview.md) + + * [Writing good readme-files](writingGoodReadmes.md) diff --git a/writingGoodReadmes.md b/writingGoodReadmes.md index 0216927..f3054b1 100644 --- a/writingGoodReadmes.md +++ b/writingGoodReadmes.md @@ -1,50 +1,62 @@ # Writing good readme-files -Writing good readme-files at the lab of digital and computational demography. - - - -## Writing readme-files Your code should be usable and reproducible for 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 I need it? - * How do I *use* it? - * How do I *develop* it? + * 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 ). In the next chapter I wrote a structure for a readme that you can use. -### Example Structure +## Example Structure + +### Title of the software Describe the essence of your software/library/code/snippet/data/whatever in one short sentence. -##### About +### 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 or a working demonstration would be cool. If your software is still in beta-status and still contains many bugs, it would be good to include a warning about the current status. -##### Installation +#### Related work (optional) + +List similar software and explain how this is different. + +### Installation How do I get started if I want to use the tool? What are the prerequisites? How to install them? -##### Usage +### Usage Include a basic example which explains the basic functionality in a simple way. You may also include more complex examples -##### Development +### 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 suiting development environment. Often times the development is very different than the usage. -##### Citation +### 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 +### 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/ + * \ No newline at end of file