Communicating research software
Software nobody hears about is software nobody reuses, cites or
funds. Communication is part of the engineering lifecycle, not an
afterthought: every release, paper and talk is a chance to reach the
researchers the software was built for. An agent is well placed to
draft these artifacts FROM the repository - README, changelog,
docs and citation metadata already contain most of the raw material.
Know the audience before drafting
The same software needs different words for different readers:
- Domain researchers (potential users): what problem it solves,
in domain language - never implementation-first.
- Fellow developers (potential contributors): architecture, stack,
where help is wanted.
- Non-specialists (funders, institutions, the public): the lay
summary - why the research matters and what the software enables,
zero jargon, one analogy allowed.
Lead every artifact with the problem solved, not the technology
used.
Software papers: support, never authorship
A software paper (JOSS, SoftwareX and domain journals) is the
citable face of the package - and it is the USER's publication, not
the agent's. The boundary is firm: help with the outline, the
research and the brainstorming; gather the raw material (the
README's purpose section informs the summary, issues and user
questions inform the statement of need, the neighbor comparison
from rseng-discovery and rseng-software-reuse informs
state-of-the-field); propose structure per the venue's template;
critique and fact-check the user's draft
(rseng-fact-checking, rseng-citation-hygiene). Never deliver a
finished, submission-ready manuscript - a publication that needs an
expert's authorship gets an expert's authorship, and the user
verifies every claim they sign (rseng-human-verification). AI
assistance with the paper is disclosed per the venue's policy
(rseng-ai-declaration). Venue mechanics and review preparation live
in rseng-software-peer-review; citation plumbing in
rseng-citation-metadata.
Release communication
For every meaningful release (rseng-publishing-releasing):
- A human-readable announcement distilled from the changelog: 2-3
headline changes phrased as user benefit ("fits are ~4x faster on
large datasets"), breaking changes with migration one-liners, and
install/upgrade command.
- Post where the software's users actually are - mailing list,
community forum, institute news, social media - not everywhere.
- Time cost is minutes when drafted from a maintained changelog;
that is the argument for maintaining one.
Talks, posters and demos
- Talk outline rule: one idea per slide, problem before solution,
a live or recorded demo beats architecture diagrams for software
talks.
- Posters: the software's one-sentence purpose in the title region,
a QR code to the repository, and a runnable example as the
centerpiece.
- Prepare the demo against dependency rot: pin the demo environment
(rseng-reproducible-environments) and have a recorded fallback.
Findability and sustained visibility
- The README is the landing page: purpose in the first paragraph,
badges that carry information (CI, docs, DOI, review acceptance),
a quickstart that works (rseng-documentation).
- Register where the community looks: a Research Software Directory
instance (rseng-software-reuse), domain registries, and the
package index's metadata fields (rseng-fair-software).
- Blog posts for milestones and interesting internals: a "how we
made X 10x faster" post recruits both users and contributors.
- Accessibility applies to communication too: alt text on figures,
readable contrast on slides and posters (rseng-ux-accessibility).
Working with this skill
This skill is source-independent: its authority is the community
communication guidance linked below.
Learn more (verified):
Related skills
Check whether any of these applies before moving on:
- rseng-citation-metadata - DOIs and citable releases
- rseng-documentation - README is the landing page
- rseng-fact-checking - fact-check the draft claims
- rseng-publishing-releasing - announcements draft from changelogs
- rseng-software-peer-review - venue mechanics and review prep
- rseng-storytelling - narrative spine for broad audiences
1---2name: rseng-science-communication3description: Covers communicating research software outward to research audiences: supporting the user's software papers (JOSS/SoftwareX-style) with outlines, gathered material and structure - never writing a submission-ready manuscript - plus release announcements, lay summaries of what the software does, talk and poster outlines, blog posts, and making a package findable to its intended users. Use when the user wants to announce, present, promote or explain their research software, asks for help with a software paper, talk abstract or release post, or when a mature package has no visibility beyond its authors. In-repo docs live in rseng-documentation; public and citizen-science narrative in rseng-storytelling; venue mechanics and review preparation in rseng-software-peer-review.4license: CC-BY-4.05---67# Communicating research software89Software nobody hears about is software nobody reuses, cites or10funds. Communication is part of the engineering lifecycle, not an11afterthought: every release, paper and talk is a chance to reach the12researchers the software was built for. An agent is well placed to13draft these artifacts FROM the repository - README, changelog,14docs and citation metadata already contain most of the raw material.1516## Know the audience before drafting1718The same software needs different words for different readers:1920- Domain researchers (potential users): what problem it solves,21 in domain language - never implementation-first.22- Fellow developers (potential contributors): architecture, stack,23 where help is wanted.24- Non-specialists (funders, institutions, the public): the lay25 summary - why the research matters and what the software enables,26 zero jargon, one analogy allowed.2728Lead every artifact with the problem solved, not the technology29used.3031## Software papers: support, never authorship3233A software paper (JOSS, SoftwareX and domain journals) is the34citable face of the package - and it is the USER's publication, not35the agent's. The boundary is firm: help with the outline, the36research and the brainstorming; gather the raw material (the37README's purpose section informs the summary, issues and user38questions inform the statement of need, the neighbor comparison39from rseng-discovery and rseng-software-reuse informs40state-of-the-field); propose structure per the venue's template;41critique and fact-check the user's draft42(rseng-fact-checking, rseng-citation-hygiene). Never deliver a43finished, submission-ready manuscript - a publication that needs an44expert's authorship gets an expert's authorship, and the user45verifies every claim they sign (rseng-human-verification). AI46assistance with the paper is disclosed per the venue's policy47(rseng-ai-declaration). Venue mechanics and review preparation live48in rseng-software-peer-review; citation plumbing in49rseng-citation-metadata.5051## Release communication5253For every meaningful release (rseng-publishing-releasing):5455- A human-readable announcement distilled from the changelog: 2-356 headline changes phrased as user benefit ("fits are ~4x faster on57 large datasets"), breaking changes with migration one-liners, and58 install/upgrade command.59- Post where the software's users actually are - mailing list,60 community forum, institute news, social media - not everywhere.61- Time cost is minutes when drafted from a maintained changelog;62 that is the argument for maintaining one.6364## Talks, posters and demos6566- Talk outline rule: one idea per slide, problem before solution,67 a live or recorded demo beats architecture diagrams for software68 talks.69- Posters: the software's one-sentence purpose in the title region,70 a QR code to the repository, and a runnable example as the71 centerpiece.72- Prepare the demo against dependency rot: pin the demo environment73 (rseng-reproducible-environments) and have a recorded fallback.7475## Findability and sustained visibility7677- The README is the landing page: purpose in the first paragraph,78 badges that carry information (CI, docs, DOI, review acceptance),79 a quickstart that works (rseng-documentation).80- Register where the community looks: a Research Software Directory81 instance (rseng-software-reuse), domain registries, and the82 package index's metadata fields (rseng-fair-software).83- Blog posts for milestones and interesting internals: a "how we84 made X 10x faster" post recruits both users and contributors.85- Accessibility applies to communication too: alt text on figures,86 readable contrast on slides and posters (rseng-ux-accessibility).8788## Working with this skill8990This skill is source-independent: its authority is the community91communication guidance linked below.9293Learn more (verified):94 - https://devguide.ropensci.org - rOpenSci dev guide (includes95 package promotion/marketing)96 - https://joss.theoj.org - JOSS, the software-paper venue9798<!-- related-skills:begin -->99100## Related skills101102Check whether any of these applies before moving on:103104- rseng-citation-metadata - DOIs and citable releases105- rseng-documentation - README is the landing page106- rseng-fact-checking - fact-check the draft claims107- rseng-publishing-releasing - announcements draft from changelogs108- rseng-software-peer-review - venue mechanics and review prep109- rseng-storytelling - narrative spine for broad audiences110111<!-- related-skills:end -->
fdiblen