# Research software papers and JOSS readiness

Decision workbook and teaching example · 2026-10-06

The completed case is fictional. Its values and decisions are not actual findings; complete your project using relevant permissions, methods and requirements.

- Project: ____________________
- Researcher and role: ____________________
- Date and version: ____________________
- Data seen before the decision: ____________________
- Aim and scope: ____________________

## Completed example

| Stage/decision | Example | Check or action |
| --- | --- | --- |
| Need | A tool for a defined scientific task | Explain users and alternatives. |
| History | Teaching demo lacks JOSS history | Link actual development evidence. |
| Tests | Known-answer mean and regression cases | List contracts and error checks. |
| Docs | Install, example, licence and contributions | Verify from a clean environment. |
| Disclosure | Assistance and human review | Apply the actual outlet policy. |

## Complete your own record

| Topic | Actual decision and reason | Evidence link and status |
| --- | --- | --- |
| Need | __________ | __________ |
| History | __________ | __________ |
| Tests | __________ | __________ |
| Docs | __________ | __________ |
| Disclosure | __________ | __________ |

## Completion checks

- [ ] A readiness matrix with actual evidence links.
- [ ] Scientific tests, installation docs and a versioned release.
- [ ] A paper draft and policy-aligned contribution/AI statements.

## Changes and limitations

| Date | Change | Data known at decision time | Reason | Consequence for claim | Reviewer |
| --- | --- | --- | --- | --- | --- |
| __________ | __________ | __________ | __________ | __________ | __________ |

## Sources and further reading

- [JOSS — Submission requirements and AI policy](https://joss.readthedocs.io/en/latest/submitting.html)
- [Cornell Data Services — Writing READMEs for Research Data](https://data.research.cornell.edu/data-management/sharing/readme/)
- [Wilkinson et al. — The FAIR Guiding Principles (2016)](https://doi.org/10.1038/sdata.2016.18)

Related guide: https://didgar-research-site1.vercel.app/en/guides/research-software-papers/