[joss][docs] - Collected Docs suggestions
sneakers-the-rat opened this issue · comments
Just going to gather all my thoughts on the docs in this issue rather than raising separate issues
- Following JOSS's checklist, you're supposed to have some statement of need in the docs. Would highly recommend at least adding a description of what the package does to the top of the README, y'all just jump right in to installation :)
- Relatedly, would be good to explain how this package is different than others - some brief description or nod to what you do differently! give yourself some credit for having good ideas :)
- Would be good to add some descriptions of what the data structures that are created at various points - eg. in the hyperparameter tuning I'm not sure what is created or how to access it.
- Not everything needs to go on readthedocs, but i'm not sure why this package isn't since there is a reasonable amount of complexity and some nice moments in the source that would be nice to have further explanation of. At least an overview of the package structure would be nice (as simple (simple as a good thing!) as it is). That and some of the "core" classes should be explained like the segmentation/diarization classes. There is some explanation in the paper within the repo, but more implementation details would be welcome.
Part of: openjournals/joss-reviews#5266
@sneakers-the-rat not sure I understand the last two points. Could you expand on those?
Yes! So for 3, eg here in the optimization part, I don't know what the database tables that would create are - in general when you have some sort of data structure that's produced or consumed by a package it's good to give some kind of abbreviated example except when it's a standard (eg. it seems like .rttm is a standard so you wouldn't necessarily need to provide an example of it, but even providing a 5-line head of one would be useful).
For 4, there are decent "how to use this" docs in the README, but I couldn't find any docs about "here is how the package is structured" or how individual classes/functions worked. Some of the classes/functions already have docstrings, so it would be pretty nice to make that work you've done doing internal API-level documentation visible by using something like sphinx and autodoc to create a documentation website.
so eg here's an old package of mine's documentation - https://docs.auto-pi-lot.com/en/latest/ it has a user guide which is "how to use this" stuff, but then individual classes have documentation like this one which is generated from its docstring .
I offered to help out with further questions on docs in case you have never set up a sphinx/readthedocs site before, so we could use this issue to chat if you'd like to pursue that - like i said not all packaged need a docs site, and the README does get the point across for basic usage, but imo it's a really good practice for long-term maintenance to document how the internals of the package work.
@sneakers-the-rat I updated the README and created a documentation page with all the information you suggested. Everything will be accessible with the next release (v0.9).
Concerning the data structures created, I think it would probably be better to write a tutorial on tuning that could be hosted in readthedocs (see #210).