[FEATURE] create readme button

[Danny-dK]

I would like a way of creating a readme.txt within Yoda in a GUI type way as the metadata button.
In general you would expect it easy to create a readme.txt by individuals themselves, but over the past 5 years I note that there is a wide variety of people not comfortable creating a nicely formatted and structured readme file. Such a thing could possibly be done by offering a 'readme' button next to the 'metadata' button and would complement Yoda as a data management platform. The terms I would consider are:

• Title (free text field or copied by the metadata file)
• Methods. More detailed description of study including measurements made (free text field).
• Folder structure (perhaps this could be automatically created by Yoda?)
• Folder contents (perhaps text boxes automatically generated by Yoda from the previous term with free text fields)
• File formats present (list generated by Yoda)
• Codebook (free text field)
• Other remarks (free text field)
• • free to add new text fields when required with a user-specified header on each.

After saving, a txt document could then be generated with a specified line length and clear header indications so that it is nicely and uniformly formatted between publications.

This would also benefit data managers that need to curate submittals to vault or for publication and is easier than communicating to the user through email that a readme file is beneficial and sending through the examples of readme file (templates).

Originally posted by @Danny-dK in #186

[stsnel]

Thanks for the proposal! We have put it on the agenda of the 14 February data manager meeting in order to gather feedback from the UU data managers.

[DorienHuijser]

I think this is a great idea, especially if we can automate some stuff there to make it easier! We probably need to discuss if this is going to be a mandatory feature just like the metadata form. If it is mandatory, why not include it in the metadata form? (although I can imagine researchers would not want all this information to be publicly available, or the form would get too extensive).

Some questions/comments about your fields @Danny-dK:

• Methods: how much of this should go in the metadata form description, and what should go in the README? If we focus on methods specifically, we could provide some more directive instructions such as:
  • what is/was your research question?
  • what data have you collected/used (to answer that question)? If applicable: who are the participants?
  • if relevant to include: how do you collect the data? For example, did you use specific technology or apparatus, a specific research design, etc. A reference to an external description will also work.
  • how did you process your data? For example, did you do some kind of quality control, data transformations, preprocessing, statistical analyses (incl. missing data, outliers)?
  • any other information that is relevant to know for colleague researchers, or a reference to a file or publication with that information.
• Folder structure and contents: could you elaborate on how this would look? Should this be 1 field instead of 2? I can imagine that it's not always very useful to list all the files, but more valuable to explain what information can be found in which file or folder.
• Codebook: I think it would be preferable if a codebook is not in a README but in a separate (machine-readable) file. However, not all researchers know how to do this. So this field should probably not be mandatory.

Components that could go either in the README or in the metadataform:

• Data and material availability: this is already in the metadata form right? I'm not sure so putting it here (links to other materials like code, related datasets, publications, and a description how to access the data if not already in the (custom) license).
• Years that the project ran
• Geographical location of the project (or is this already in the metadata form?)
• Researcher name(s), institute(s), department(s) + contact person for the dataset (if available) -> Some of this is already in the yoda metadata though, but not fully I think.

[Danny-dK]

@DorienHuijser I wouldn't make the readme button mandatory as there are many different ways of adding the appropriate documentation depending on the discipline. I would make it optional so that researchers that do not know what documentation to enter are helped by this functionality. I think it is the task of the one with Yoda data manager rights to check that appropriate documentation is present.

I also would not put this readme info in the metadata. One of the 'complaints' we generally get is that the metadata form is already very long. Making it longer would probably overload the researcher in the amount of mandatory things to fill in.

what is/was your research question?

In general good to include, but I would imagine this is already given in the metadata section 'Description'. But could also be mentioned here.

what data have you collected/used (to answer that question)? If applicable: who are the participants? if relevant to include: how do you collect the data? For example, did you use specific technology or apparatus, a specific research design, etc. A reference to an external description will also work.

That would be under "Methods. More detailed description of study including measurements made (free text field)" If you describe measurements, you would be describing the data collected and used methods. But good to emphasize what is expected to the researcher.

how did you process your data? For example, did you do some kind of quality control, data transformations, preprocessing, statistical analyses (incl. missing data, outliers)?

Good to add.

any other information that is relevant to know for colleague researchers, or a reference to a file or publication with that information.

My intention for 'other remarks'. Indeed good to emphasize on the exact meaning.

I would say that it is good to emphasize on the meaning for different sections, but also would be hesitant to give long lines of text as guidance for researchers to read through. So should be a balance.

Folder structure structure and contents: could you elaborate on how this would look? Should this be 1 field instead of 2? I can imagine that it's not always very useful to list all the files, but more valuable to explain what information can be found in which file or folder.

Folder structure would be 1 field with a graphical textual representation of the folder structure.
Folder contents would be 1 field for each folder describing what type of files can be found there. Indeed not listing the files, more on what information is found there.

Codebook: I think it would be preferable if a codebook is not in a README but in a separate (machine-readable) file. However, not all researchers know how to do this. So this field should probably not be mandatory.

Indeed, at WUR we are going to separate it to a csv that lists all abbreviations, data points, variables, etc, with explanations. Perhaps a different button 'codebook' could be added that creates a csv type thing?

Components that could go either in the README or in the metadataform:

These are in the metadata form already and can be elaborated upon there (even in multiple fields).

[Danny-dK]

I think this feature request could be closed for now. In the accompanying discussion #186 I wrote:

"readme.so could be a platform to use and there is a pull request available octokatherine/readme.so#274 in which one can export and import templates that can be used by researchers https://readme-7o4rklwrq-katherineoelsner.vercel.app/editor. It does seem that readme.so is not really very much active as pull requests seem to take a long time. I guess for now it would be best to have your own template created (in markdown or just simple txt file) and spread that within the institute for researchers to use."

@stsnel @lwesterhof Leaving it up to you to close or keep open (fine either way).