Improve guidelines for API documentation

[arfon]

Our guidelines for API documentation are currently limited.

Extracting a comment from @dpsanders in an email thread about this topic:

Currently, the Submission requirements section does not mention documentation at all.

I think we should add an explicit requirement for both narrative and API documentation in that section.

Something like:

"The software should be accompanied by narrative and reference (API) documentation that is separate from the code itself. (This documentation may be located in a separate repository.)"

/ cc @kbarnhart @pdebuyl

[pdebuyl]

From https://joss.readthedocs.io/en/latest/submitting.html

your software should be full-featured, well-documented

There is already a proper item in the review criteria.

Documentation

There should be sufficient documentation for you, the reviewer to understand the core functionality of the software under review. A high-level overview of this documentation should be included in a README file (or equivalent). There should be: (...)

In principle, we already request a proper documentation. What I think is missing:

1. An item in submission requirements https://joss.readthedocs.io/en/latest/submitting.html#submission-requirements Ex: The software should have a high-level documentation, whose target audience is the users of the package.
2. An item in the review checklist, under "Documentation": "High-level documentation: Is there an easy to find textual documentation for the final user?"

Proposed change to the review criteria

Documentation

There should be an easy to find, high-level, textual documentation for the final user. This documentation should be sufficient for you, the reviewer, to understand the core functionality of the software under review. A high-level overview of this documentation should be included in a README file (or equivalent). There should be: (...)

Suggestion: some software have an extensive and informative README that fills in the role of the documentation. We could acknowledge this as a minimal (but accepted) form of user documentation.