Review Suggestions to the repository structure

[spanichella]

0) I would refactor the current README.md. Specifically, let's separate the description of the repository and the design of the study from the actual information concerning the installation of the scripts, etc. We should transform the first page to its essential information and links, see the following suggestions for it.

We need to have on the main page information like

• what the goal of the project is with some images on what the problem we are trying to solve. It is good to have figures that make more visual the problem addressed.
• little overview on Ticket Tagger research (which is already there) with clear references on what was the limitation of that work and what aspects you decide to improve. So that once we arrive at the methodology section "we know why we do what we do"
• what we make available (data, scripts, etc.) - this is already there, probably is god to sort anticipate it, we should have a table of content in Markdown style (since the repository is growing) as here: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
  • I would replace "Tasks Overview" -> "Extension Points"
  • if possible a gif or video on the usage of the code in the script section
  • add a section "References" to the main read me file, so that the original paper is referred to the repository

1) before going to a low level of detail, we could add a the end section like

• "Contacts" - with names of the research team (i.e., names) - possibly with your pictures
• Possibly linking the web page of the course https://www.ifi.uzh.ch/en/seal/teaching/courses/sme.html
  • the project was, in the end, run in the context of a course at the UZH (I think the UZH would appreciate that we acknowledge this)

2) if possible I would change a few things in the other folder of the repository

• I would use "code-pipeline" instead of "scripts": containing the code to run the actual pipeline
• OPTIONAL folder "previous results": reference to previous paper and tools that used the previous version of the pipeline

3) Is good to have almost all tables of the results and the discussion in one main low-level folder. All reported there. On the main page should go a summary of the main findings, with reference to the low-level results.

4) About the folder on the "code pipeline" I would use add to the structure of the readme README.md of the GUIDELINE information similar to the following:

"Setup Guide and Program Description" The goal of this part is to give a brief description of ....

Supported Operating Systems

• Windows ..."

Pre-Requisites

• Python ...
• Memory: XX GB ...
• For usage on Windows, add ...

Setup Information For information about setup and use, please refer to the instruction provided here.

Pipeline architecture description and figure ...

Pipeline installation ...

TO RUN THE TOOL .... ... "

8) I would rename the section "Methodology" in "Study Methodology" (or something similar) to describe what the competition actually does

• There I would add more description on what in the RQs we tried to investigate and the rationale for some design decisions. For the moment we report what we do, but not the why.

[ChristianBirchler]

Thank you for the detailed suggestions. We will transform the readmes as described and let you know as soon as possible.