rseng-documentation

# Documenting research software Use this skill when creating or improving any documentation for research software: a README, in-code comments and docstrings, API/CLI references, project files like CONTRIBUTING or CHANGELOG, a hosted documentation site, or a narrative Research Software Story. Good documentation makes software understandable, reusable, and sustainable - it tells others (and your future self) what the software does, how to use it, and how to contribute. ## Separate the two levels first Decide which level the user needs before writing, because audience and content differ: - Project documentation - the software as a whole: purpose, audience, installation, usage, licensing, contribution. Lives in README, INSTALL, CONTRIBUTING, LICENSE, CITATION. Helps people use and adopt the software. - Code documentation - how the code works internally: comments, docstrings, architecture notes, API references. Helps people develop, deploy, and sustain it. Both matter; keep them consistent. Installation and usage often straddle the line and serve users and developers alike, so link between the two rather than duplicating. Cross-cutting rules for all documentation: - Keep it accessible, clear, consistent, and regularly updated; cover all key aspects and invite feedback. Outdated docs can be worse than none. - Generate it automatically where possible and use standard formats: Markdown, reStructuredText, HTML, PDF, or a wiki. - Store documentation in the repository...