search

gasparl / citapp_pc

CITapp: a response time-based Concealed Information Test lie detector web application. This method aims to reveal whether or not a certain information detail (e.g. a photo taken from the scene of a recent burglary) is known to the tested person.
https://gasparl.github.io/citapp_pc/CITapp.html
BSD 2-Clause "Simplified" License
1 stars 3 forks source link

[REVIEW] Verbose Review #8

Closed vsoch closed 5 years ago

vsoch commented 5 years ago

Verbose Review

I've created issues for each comment, each referenced in https://github.com/openjournals/joss-reviews/issues/1179. Here I will write more general feedback in response to the review checklist.

Repository

The source code is available on Github at the repository url. As a suggestion, I would name the license file just LICENSE (which I see more commonly than LICENSE.txt or similar) however if you have compelling reason to leave as is, this is probably ok.

The README is very rich with information, especially the Introduction serves well to (better) introduce the reason to have the task than the paper itself. Since it's an actual web based task, I would suggest to add some screen shots to the README as you are describing the task. Currently, it's very dense in terms of text and the user is forced to mentally visualize what it might look like.

The release version is correct, v1.0.0.

@gasparl is the only contributor, so he definitely has made reasonable contribution to the software :) If you ever have additional contributors, you should add an AUTHORS.md file, and a CONTRIBUTING.md file.

Functionality

My main comment here is that there needed to be better instructions for how the user can actually deploy the file. It's fairly obvious to put the html file on a server, but it's not obvious that the user would need to clone, put somewhere, etc. As another suggestion, you might deploy a container so it's immediately usable (I created an issue for this here

For the functional claims, I'll be glad to test when a preview / deployment is available. Let's leave this (and performance evaluation) undone for now.

Documentation

I created this issue to suggest that the statement of need could be better explained in the paper. It's not clear who the target audience is, or why this was created in the first place. It would also be good to have a real world example of how/when it's used. Why/when would I care to use this?

It looks like all dependencies (css and js) are provided in the repository, so we are good!

For documentation, it looks like the same content of the README is provided as a PDF but I'm not drawn to it unless I look at the files in the repository. I would add a note (and link) in the README that says "hey! If you need to download the documentation, here it is!"

I'm not sure if this application warrants any kind of testing, but I can give this feedback when the preview is available on Github pages.

Finally, community guildelines (how to contribute, ask for help, and the code of conduct) are all missing, I've opened an issue for that as well.

I'll now update the checklist, and we can continue conversation on each of the issues here. Looking forward to previewing / testing the web page!

gasparl commented 5 years ago

Thank you for your thorough review. Here I just reply to those few things that were not mentioned in separate issues.

vsoch commented 5 years ago

Great work @gasparl . I had a few outstanding questions in the other issues, but I'm happy with the changes once we get those closed up (and I'll make final edits to the joss-reviews issue and finish checking off boxes).