Improve Documentation vs Wiki vs Google Group

[SamGuay]

First, I want to say that formr is awesome and you all rock for building this! 💯

(Please note, this is the first time ever I open an issue so thank you for your patience and advice 🤓. It has ended up being quite verbose because of different requests being made, but they were related so... Just tell me and I'll split it in 2 or 3.)

---

So I have been using and searching through the documentation, wiki, mailing list(google group) for quite a while now and here's some features or enhancement requests that I think would help a great deal the community, especially the new GitHub users (I include myself here).

Here's the list with some explanation below:

• 1. Make the website documentation searchable
  • Wrap the website documentation in Bookdown, MkDocs, Docsify, or alike.
• 2. Make the Wiki and the website documentation content the same.
  • Add most relevant questions from the mailing list to the doc.
• 3. Improve the Contributing.md file

1. Make the website documentation searchable

Having a documentation where users can type whatever keyword they have in mind and search throughout the documentation would help users find the information quicker and they are more likely to find what they are looking for before asking a question on the mailing list.

I am pretty sure you already use a documentation generator but I gave MkDocs and Docsify as examples of searchable documentation. Obviously, using R to generate the documentation would be logical, so I reckon using Bookdown could be a suitable option. This could be a community-based documentation/FAQ where people could contribute to it. As of now, I am now sure where I have to go to add some documentation.

2. Make the Wiki and the website documentation content the same.

As of now, it is quite difficult to know where to look to get an answer. It is not clear whether the website or the wiki contains the same documentation or which one has the most complete documentation. Of course if 1. is implemented in the near future, this wouldn't be a problem. Anyhow, I think having the doc only in one place could facilitate the searching process.

Related to this, I think adding most relevant questions or generic question from the mailing list to the documentation (once a working answer has been given) would benefit the community. Is there already a curating process or you simply answer as people ask ? As a proof of concept, I'll explain what triggered me to open this issue:

I use a tablet when my participants come to the lab and I can have > 3 people answering forms back to back while they wait to be scanned. At first, I was deleting cookies every time because otherwise it would bring me back to the thank you page at the end of the run. This was not convenient at all. I wasn't sure how to frame what I wanted to do so I had to look through all the documentation available to finally stumble upon those two questions that seemed relevant for my problem:

• formr's google group question related to this can be found here and there, but no explicit solution:
  • New users in the same device
    • The person did not apply the right solution, but the right solution was given.
  • Deleting cookies after redirect?
    • But not relevant to me as of now.

So I finally made it work with solution provided in New users in the same device after having tried the (final) incorrect solution provided by the user. This proves that users could benefit of having it clearly written down.

This simple scenario where someone would like to have participants log out of their current run once their done and start the same run for a new participant is really easy to do once you know how, but not easy if you don't know how to do it or where to find the solution... (My bad if I have missed where in the documentation this solution is provided).

3. Improve the Contributing.md file

Based on my experience of 2., I would happily provide an explicit written procedure for this scenario in the documentation and more... But as of now, I find the Contributing.md file not really helpful in telling me how I am supposed to contribute... Well, can we contribute even though we are not so tech-savvy (I guess we all have to start somewhere)?

Cheers,

[rubenarslan]

Hi Sam,

thanks for taking the time to help us improve our documentation. I'll share my own thoughts in response.

1. Searchable docs.That's a good idea. The Wiki is searchable I guess, but the formr.org docs aren't. We don't use any standard for generating docs. Mainly because I didn't know about such things back then, but also because I like being able to reuse parts of the docs in places where people will need them (e.g. run component documentation is available directly in the run). I guess the easiest thing to do for now would be to make a custom Google search query thing that searches the formr wiki, issues, docs, and mailing list. I don't know how easy that is.

2. Unifying Wiki and website docs. I'm not sure whether that's a good idea. Most of our users do not know how to do pull requests, so they cannot easily contribute to the Website docs. Some manage to make Wiki entries (often at my behest after I answered a mailing list question), although most have to sign up for Github to do so. Almost all manage to use the mailing list. And then there's the dark matter knowledge of people who just email me or Cyril (sometimes I permit this, if people cannot share problems publicly). So, a more realistic thing is probably to improve the pipeline:

Mailing list -> Wiki -> Website docs

Maybe we can also automatically integrate the Wiki into the website, I'll look for a way. The thing is, we're stretched pretty thin right now, with two thirds of the formr team adapting to parenting another demanding baby. So, any help is welcome. It's often easier for me to find the time to correct someone else's explanation than to write a useful explainer myself (curse of knowledge etc.).

We will also have to link to the soon three tutorial papers on formr at some point.

3. How to contribute. That's a very good point. I've never looked at this document in a long time. Ok, so here's how you can help. Go to that file. Click the edit pencil. Add the information I've compiled here and elsewhere in a friendly organized way. Save. Github will help you submit a pull request, which we can then accept. Same holds for typos in the website docs etc. What Cyril had added there is just relevant to people who want to contribute to programming formr, which is the fewest of our users.

Another way you can help: In a case like your query, add the question and the right answer to the Wiki FAQ: https://github.com/rubenarslan/formr.org/wiki/FAQ---frequently-asked-questions
Your query is definitely frequently asked. Sliders without defaults are another one. I just hardly find the time to respond to the mailing list, even though it'd probably be more efficient to organize things in the docs from time to time.