Documenting Functionality

[TanyaS08]

This is primarily relating to the following point in the reviewer checklist regarding Documentation

Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?

To me I feel that a core argument justification of releasing this software is the idea that it can by modified and used for other monitoring applications/setting (I love the fact that this type of app development is being shared for re-use 🐣). However, since this means re-users/potential modifiers might be quite daunted by where to start in terms of what script does what I wonder if it could be a bit more extensively documented? I think script flow chart figure is a great starting point but it might be nice to also attach some sense of functionality as to what each script/group of scripts does. This could be something simple like scripts x,y,z deal with the raw sightings data, I,j,k, with report generation etc. Do the colours in the figure maybe represent that already?

I don't want to generate undue work though so I'd be interested to see what @salix-d thoughts are and if they think that the documentation is sufficient (or have other thoughts). Of course as the authors y'all should also have a say!

[salix-d]

The arrows/their colors do seem toindicate which app is being used, and each app seems to have its own functionnality.

I also like that the code is commented. It could be beneficial to have roxygen type of documentation in the files, like defining the arguments of each function. That does help contributors/re-users, but I don't know if it's necessary. I don't see many packages that have documentation for internal functions.

Kind of related to that though, I don't think I saw community guidelines

Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

[TanyaS08]

Okay I can see an argument that the figure does do enough lifting on its own. However may I then suggest that some consideration be given to the colours of the arrows as the colours themselves are not very divergent from a colour vision deficiency perspective. Perhaps an an additive to the colours different arrowheads (as you did for the figure in the actual manuscript) could be used.

[salix-d]

Using different line types is also a great option. I would suggest a legend as well and having a pdf/text version for screen readers.

[leahcrowe]

Kind of related to that though, I don't think I saw community guidelines

Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Thanks for catching the absence of community guidelines. I added some more details regarding third party contributions, issues, and support at the beginning of the README

[leahcrowe]

Thank you both for your comments and considerations regarding the description of the script structure and specifically the flow chart figure. I considered your comments and decided to include both a short description of each file as well as an updated version of the flow chart. Let me know if you have any suggestions after considering these changes!

[salix-d]

I added some more details regarding third party contributions, issues, and support at the beginning of the README

Hi, I did see the line you added. I think it could be more precise for the third party contribution. Often when contributions are accepted there's a code of conduct or some kind of specifications. It's also ok to not accept any, but then it should be stated clearly. Here's an example: https://github.com/ropensci/concstats#development

[leahcrowe]

Hi, I did see the line you added. I think it could be more precise for the third party contribution. Often when contributions are accepted there's a code of conduct or some kind of specifications. It's also ok to not accept any, but then it should be stated clearly. Here's an example: https://github.com/ropensci/concstats#development

Thank you for further clarifying these points! I added a "Contributions" section at the end that now includes a Code of Conduct, as well as some further clarifications on submitting issues and code changes.

In working on this, I also added a bit of an intro to the README to better introduce what can be found in the repo, and updated our license so that there is no copyright.

[TanyaS08]

Great - I'm happy with the changes so I'm closing this issue. Thanks all 😊