rseng-documentationlisted

Covers how to document research software at every level: writing a README, code-level docs (comments, docstrings, API and CLI help), project docs (INSTALL, CONTRIBUTING, LICENSE, CITATION, changelog), publishing hosted documentation with Read the Docs, and capturing a Research Software Story. Use when the user asks how to write or improve a README, decide what documentation their project needs, add docstrings or inline comments, document an API or CLI, set up Sphinx/MkDocs/Doxygen, host docs on Read the Docs, structure a docs site, or write the narrative context and history behind a project. For outward-facing papers, talks and announcements see rseng-science-communication; for public and citizen-science narrative see rseng-storytelling.
fdiblen/rseng-agent-skills · ★ 20 · Data & Documents · score 81

Install: claude install-skill fdiblen/rseng-agent-skills

# 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