some work towards #416

CONTRIBUTING.md

@@ -1,6 +1,34 @@
-# Before you start working
+# How to improve formr
+formr is open source software. You are welcome to help improve it. Depending on your technical background, there are several options.
 
-Development to this project is done only using Git Flow workflow. 
-Study it, understand it, use it.
+## Improve the software
+If you know the relevant software stack (e.g., R, PHP, JavaScript, CSS, HTML), you can send us pull requests on Github to quash bugs, add features, add tests, etc.
 
-For a quick introduction see https://gist.github.com/JamesMGreene/cdd0ac49f90c987e45ac
+If you want to test formr or contribute to its development, follow our [instructions](https://github.com/rubenarslan/formr.org/blob/master/INSTALLATION.md).
+
+The setup instructions are not suitable for production, i.e. running a secure formr installation on the public web.
+
+## Improve the documentation
+formr allows for very complex study designs. Not all of the potential use cases are documented. In some places, the documentation is out of date or hard to understand.
+
+### Add your own use case
+If you have implemented a study in formr, especially if you've done something difficult, we and other users would greatly appreciate, if you write up a case study.
+
+Ideally, that would consist of some description of the study design, a link to the preprint or publication if applicable, as well as the exported study JSON file (Run->Export).
+
+### Ask and answer questions in the Github Discussions
+We use [Github Discussions](https://github.com/rubenarslan/formr.org/discussions) for community support. We try to find the time to answer questions. If you answer some of the questions we didn't get to yet, we'll try especially hard to answer your own questions. We also appreciate if you post back with the solution, if you found one yourself.
+
+### Improve the documentation
+Unfortunately, our documentation currently lives in four places:
+
+- The old [Google Group](https://groups.google.com/g/formr) which we closed down because of the spam.
+- The new [Github Discussions](https://github.com/rubenarslan/formr.org/discussions)
+- The [repository Wiki](https://github.com/rubenarslan/formr.org/wiki) which is intended for case studies, brief tutorials, frequently asked questions, and so on.
+- The [documentation on the website](https://formr.org/documentation) itself, which is accessible while using formr.
+
+Editing the Github and the Wiki should be easy. We use Markdown, which is basically plain text.
+
+The documentation files for the website are on [Github](https://github.com/rubenarslan/formr.org/tree/master/templates/public/documentation). Even if you are not a technical person, the documentation is just plain HTML, so easy to edit. You can edit it directly on Github using the "Pencil" button. This will create a pull request, i.e. we get a chance to review your change before it makes it into the website.
+
+We appreciate any efforts to move questions/solutions from the Google Group to the Wiki or website documentation, or from the Wiki to the website documentation.

README.md

@@ -1,8 +1,11 @@
 # formr survey framework
-#### how to cite
+## Contributing
+See [Contributing](https://github.com/rubenarslan/formr.org/blob/master/CONTRIBUTING.md) if you want to help improve formr?
+
+## Citation
 See [formr.org/public/about](https://formr.org/public/about) if you are publishing research conducted using formr.
 
-#### chain simple forms & surveys into long runs, use the power of R to generate pretty feedback and complex designs
+## chain simple forms & surveys into long runs, use the power of R to generate pretty feedback and complex designs
 
 This is a framework that allows you to create simple and complex studies using items spreadsheets for the surveys and "runs" for chaining together various modules. 
 
@@ -14,7 +17,7 @@ There are three main components: surveys, runs and the R package.
 #### ask questions, get data
 Surveys are simple or complicated forms and surveys used to gather information in a single session.
 
-There is a wide variety of items to choose from: text and number inputs, Likert scales, sliders, geolocation, date pickers, dropdowns and many more. They are geared towards power users, so instead of dragging and dropping elements till your fingers bleed, you upload item spreadsheets that can easily be re-used, combined and shared.
+There is a wide variety of items to choose from: text and number inputs, Likert scales, sliders, geolocation, date pickers, dropdowns and many more. They are geared towards power users, so instead of dragging and dropping elements till your fingers bleed, you upload item spreadsheets that can easily be re-used, combined and shared. The format is loosely based on the [XLSform standard](https://xlsform.org/).
 
 ## Runs
 #### control your study like a boombox
@@ -44,8 +47,8 @@ The following designs and many more are possible:
 
 Wherever you use R in formr you can also use the functions in its R package. If you want to use the package in a different environment, you'll need to install it using these two lines of code.
 
-	install.packages("devtools")
-	devtools::install_github("rubenarslan/formr")
+	install.packages('formr', repos = c('https://rforms.r-universe.dev', 'https://cloud.r-project.org'))
+
 
 The package currently has the following feature sets