The problem in one sentence
Decide three things so that a reader finds what they need and can trust it: what a repository's documentation must say, how its pages are separated by purpose, and what a code comment must carry.
Two levels
| Repository |
which pages, with what content |
documentation structure, README content, documentation taxonomy, research software documentation |
| Code |
what a comment says |
code comment quality assessment, docstring conventions, code-comment inconsistency |
Names for the same things
- Page forms: Diataxis, tutorial, how-to guide, reference, explanation.
- Acceptance bar: JOSS review criteria (Journal of Open Source Software).
- Operational rules: Ten Simple Rules (Lee 2018).
- Comment guides: PEP 257 (Python docstrings), the Google style guide.
- Design view: comments as design (Ousterhout 2018).
Search terms tried, three ways
- Academic: code comment quality, README classification, scientific software documentation.
- Acronym: JOSS, PEP, SLR (systematic literature review).
- Author: Procida, Lee, Prana, Pascarella, Wen, Rani, Ousterhout.
Practitioners' names, beside the field's
| topic types: concept, task, reference (GitLab); modules: concept, procedure, reference (Red Hat) |
documentation taxonomy, page forms (Diataxis) |
| front-load keywords, scannable content (Microsoft) |
signal the structure, overview first |
| short description of a module (Red Hat) |
abstract, overview first |
| spell out on first use (Google) |
define before use |
| delete dead docs, docs change with the code (Google) |
code-comment inconsistency (Wen 2019) |
| README sections, standard README |
README content (Prana 2019) |