Metadatamanagement: Improve documentation of questionMetadataPreparation process

[rbirkelbach]

• [x] Add who and how (Issue) needs to be contacted at the zofar-team
• [x] request at an early stage, preferably even before the other work on the SUF is started
• [x] consider Zofar sprints
• [x] add a template for what zofar needs (https://github.com/dzhw/zofar/issues/333#issuecomment-601096001)
• [x] add, that and why we use pages and why (not) questions
• [x] atm (still? ask Christian) questions are not the questions we need but a technical dimension that we can't work with
• "by default" zofar links the variables.csv to pages, not questions
  @rbirkelbach does the interfer with the paths you defined when using the pages instead of questions?
• [x] link readthedocs, the repo and the introduction more easily
• [x] Make it even clearer that one always needs to transform from zofar format to handcrafted if it's questionmetadata provided by zofar.
• [x] What needs typically be altered at the handcrafted stage after we received jsons from zofar? conceptIds come to mind
• [x] Add ~link~ explanation to mdm-documentation for importing the finalized jsons (currently there's no explanation in the mdm documentation how to click the upload button. Will add it, see https://github.com/dzhw/metadatamanagement/issues/2498)
• [x] Add a note about how the images should look like (e.g. regarding header/footer, buttons) (differs between questions and pages)
• [x] Add a note on how to further edit the instrument file? (see for example gra2005 (wave 3) and ssy21)
• [x] Add a note on how to further edit the variable file?
• [x] Add section what typically needs to be checked. Is it enough to import them to the mdm, check whether there's an error message and if not, click through the question details pages? (In this case, however, metadata that is not directly displayed via fields in the MDM would not be checked.) A standard checklist should be drawn up showing which points need to be checked exactly, by whom (SHK/WiMi?) and where (excel/MDM).
• [x] Check for not escaped symbols.
• [x] add hint to install Rtools for windows users
• [x] How to deal with "preload"-variables? Imo: I'd leave it as is.
• [x] input from ssy21: https://github.com/dzhw/ssy21/issues/38
• [x] Info von Johanna bei Frageerfassung gra1989/1993:

Die Formatierung des Textes in der Spalte "additional question text" ist egal. Es muss einfach nur erfasst werden, taucht aber später nirgends sichtbar auf ;)

• [x] Info von Maika bei Frageerfassung gra1989/1993 (gilt nur wenn keine Zofar-Lieferung, sondern manuelle Erfassung der Texte):

In der Vollversion von Adobe Acrobat Pro DC ist auch das OCR Verfahren unter "Scans verbessern --> Text erkennen" zu finden. Damit werden Bilder auf Text durchsucht und Textstellen erkenntlich gemacht. Dies trägt dazu bei, dass man Texte aus den PDFs zumeist einfach nur noch im Copy-Paste-Verfahren in die Excel einfügt. Damit ist eine händische Übertragung überfällig und es erleichtert den Arbeitsprozess sehr deutlich! Da die Qualität der gescannten Dokumente hierfür relativ gut sein sollte, würde ich für zukünftige Scanaufträge außerdem das Scannen mit einer Auflösung von 600(dpi ??) empfehlen; die Scans sind deutlich schärfer, somit ist Text klarer im OCR-Verfahren zu erfassen.

[UteH]

@rbirkelbach How about one of us (@anneweber @svietgen @UteH @McWallis) tests/reviews this issue :)?
Then we know for sure we know how to work with it and how to edit the documentation?

[rbirkelbach]

I'm in favour of that.

[UteH]

wie vor ein paar Wochen besprochen, hier noch meine Anmerkungen zur Anleitung zu https://dzhw.github.io/questionMetadataPreparation/

1. Verlinkung „introduction“

ich habe gerade wieder nicht die Attribute für questions gefunden. Dann ist mir irgendwann eingefallen, dass ich dich das ja schon mal gefragt hatte und sie dann hier waren: https://dzhw.github.io/questionMetadataPreparation/articles/question_metadata_preparation_introduction.html

• readthedocs: Ich habe den obigen Link schon in readthedocs unten eingefügt -> nochmal besser machen

• MetadataPreparation: Könntest du das vielleicht auch noch bei https://dzhw.github.io/questionMetadataPreparation/ bzw. https://github.com/dzhw/questionMetadataPreparation/ (das synchronisiert sich ja automatisch, oder?) einbauen?

2. Weitere Ergänzung zur readme

Zudem hätte ich noch folgende Ergänzungsvorschläge für die Anleitung bei https://dzhw.github.io/questionMetadataPreparation/

library(questionMetadataPreparation)

setwd("")
# change \ to /

getwd() 
# doublecheck the working directory

(ich weiß, dass sind eher allgemeine R-Infos, aber ich denke für uns wären sie auf jeden Fall hilfreich, da wir ja kaum mit R arbeiten)

variables import csv:

[rbirkelbach]

What do you mean with: " Add a note on how to further edit the instrument file? (see for example gra2005 (wave 3) and ssy21)
Add a note on how to further edit the variable file?"
Ie. Can you give example files with complete filenames and preferably also paths?

[anneweber]

Hey @rbirkelbach :) ,

I meant the following points:

• Add a note on how to further edit the (Zofar) instrument file (see for example gra2005 (wave 3) and ssy21)

  • I think the first step is to check whether the instrument file (=screenshot file) meets our requirements. See Utes File \\faust\Abt4\FDZ\4_Datenaufnahme\Intern\Nacaps\nac2018\v1.0.0\4_Dokumentation\Feedback_Zofar_Lieferung.pdf, section "3 Instruments"
  • For gra2005 and ssy21 we have also added further information (notes, annotations and drop-down-lists; so far there is no fixed standard for this.).
    
    
    
    • gra2005: https://metadata.fdz.dzhw.eu/public/files/instruments/ins-gra2005-ins3$-2.0.0/attachments/gra2005_W3_Main_Questionnaire_de.pdf
    
    
    • ssy21: https://metadata.fdz.dzhw.eu/public/files/instruments/ins-ssy21-ins1$-2.0.0/attachments/ssy21_bi_Questionnaire_de.pdf
    
    

• Add a note on how to further edit the (Zofar) variable file

  • I think the first step is to check whether the variables file meets our requirements. See Utes File \\faust\Abt4\FDZ\4_Datenaufnahme\Intern\Nacaps\nac2018\v1.0.0\4_Dokumentation\Feedback_Zofar_Lieferung.pdf, section "2 Variables"
  • It should then be described what exactly must be done with the information provided on the variables.

[rbirkelbach]

https://github.com/dzhw/questionMetadataPreparation/pull/18 Please review my pr, @svietgen, @McWallis , @anneweber , @UteH (I don't care who does it, but I want to make sure I haven't missed anything and that it's understandable).

[anneweber]

Hi @rbirkelbach , lieben Dank für's Anpassen der Doku. Könntest Du noch hier (oder in das andere Issue) schreiben, wo genau man sie findet? @svietgen @McWallis @UteH Wir müssten uns noch mal abstimmen, wer das idealerweise machen sollte und Zeit für ein Review hat/bekommt.

[rbirkelbach]

You find the changes in the pull request, here: https://github.com/dzhw/questionMetadataPreparation/pull/18/files
The documentation will be built as a website after merging.

[anneweber]

Hi @rbirkelbach , danke Dir. Ich würde mir das heute mal anschauen. Allerdings wäre es dabei hilfreich, wenn man ein Gesamt-Dokument hätte, in dem man kommentieren kann. Könntest Du uns sowas zur noch zur Verfügung stellen?

[rbirkelbach]

You can comment within the diff by hovering with the mouse over the diff and then clicking the plus button that appears. I'll create a pdf nevertheless.

[rbirkelbach]

Here are the documents.
README.pdf
question_metadata_preparation_introduction.pdf
general_workflow_and_tips.pdf

[rbirkelbach]

[ ] Add explanation how to add multiple questionImages for one question.

[anneweber]

Hi zusammen @rbirkelbach @UteH @McWallis (@svietgen ),

ich bin jetzt einmal durch mit dem Review der Doku.

Wie schon gestern gesagt, ist es mir sehr schwer gefallen, weil die Gesamtstruktur der zukünftigen Doku (verschiedene Dokus für verschiedene Zielgruppen? verschiedene Doku-Orte (Zusammenspiel von readthedocs, GitHub, Weiterem?)) noch nicht klar ist.

Ich habe jetzt versucht, die Informationen aus den drei pdfs möglichst alle in einem Dokument chronologisch zusammenzuführen. Ich habe dafür die bestehenden Textbausteine anders zusammengesetzt und teilweise etwas angepasst, sodass sie dann bei der veränderten Struktur ineinandergreifen. Dies habe ich ohne Änderungsmodus gemacht.

Innerhalb dieses Dokuments habe ich dann in den bestehenden Textbausteinen noch kommentiert und Änderungsvorschläge eingefügt.

Das Ergebnis findet Ihr hier:
Review Anne.docx

@McWallis Vielleicht könntest Du mal schauen, was Du von meinem Vorschlag hältst?

Ich würde mich hier dann auch erst mal ausklinken.

---

Edit: Ergänzt werden sollte noch

• Wann kann man den Zofar-Block einfach skippen?
• Bzgl. Anpassung nach convert zofar zu handcrafted: bei z.B. Nacaps sollen gar nicht alle Fragen, die von Zofar geliefert werden (weil in Programmierung enthalten), veröffentlicht werden. Diese müssen daher entfernt werden. Damit hängt dann auch die Anpassung von Folgefragen (etc.?) zusammen.

[rbirkelbach]

@rreitmann we want to show how a pull request can be done with github during the next review.

[rbirkelbach]

Thank you a lot, Anne. I'll take a closer look in the next days!

[rbirkelbach]

updated documentation is merged into master