You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.)"
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:
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.
Our guidelines for API documentation are currently limited.
Extracting a comment from @dpsanders in an email thread about this topic:
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
The text was updated successfully, but these errors were encountered: