update README.md

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)
 

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/
+ *