Write a research-software README around a verifiable first use
Write a research-software README that gives readers a checked first-use route.
About 5 min read · Allow extra time for the practical checks
Explain what the research software does, what a new user needs and how they can check one small first use. A README should help someone move from finding the project to understanding a result they can inspect. A list of features is insufficient if the reader cannot identify the right input, the supported setup or the expected output.
This guide concerns writing project documentation from established software behaviour. It does not implement or test a real program, select a software licence or guarantee reproducibility of a research result. Obtain the relevant technical checks and permissions before describing a setup, example or release as verified.
Choose the reader’s first task
Name the intended user and one realistic starting task. Distinguish a researcher trying an example from a developer changing the code. A short route through a demonstration can point to detailed installation or developer documentation without making the first page reproduce every technical reference.
The Turing Way’s README guidance, checked on 2 November 2026, recommends explaining the project’s purpose and audience, how to begin and where key resources are. For software, it also identifies installation, testing and other running requirements as useful documentation. Use that guidance with the actual project; its case-study structure is not a compulsory template.
Write the first paragraph so that it states the software’s task and scope. Separate a current capability from a planned feature. If the software groups supplied labels, do not describe it as validating the underlying observations or interpreting a study’s findings.
Work through an original fictional README plan
The program, files and behaviour below are invented teaching material. No real software release, successful execution or research result is represented. The example supplies no working command to run.
Imagine a fictional teaching program called Panel Counter. Its proposed demonstration takes a CSV with a panel_type column and groups rows by the supplied category. The design includes a small example file and calls for a separate count-summary file. A draft README says only: “Install the package and run the analysis.”
That instruction leaves several gaps:
| First-use question | Detail the fictional README needs | Check before calling the real equivalent verified |
|---|---|---|
| What does the program do? | Count supplied category labels in a teaching CSV | Confirm actual behaviour and avoid calling it label validation |
| Which input should a beginner use? | The demonstration file supplied with the chosen release | Confirm that file is included and identify its location |
| What setup is supported? | The environment and dependencies used for the documented example | Check the actual setup rather than copying an old requirement list |
| What should appear after the example? | A named count-summary file with described columns | Compare the observed output with the documented expectation |
| What does a mismatch mean? | A route to relevant checks or support | Do not declare every unexpected output a user error |
A proposed introduction could read:
Panel Counter is a teaching program designed to group rows by the category supplied in
panel_type. Start with the demonstration CSV for the release you are using. The first-use instructions should identify the supported setup, the exact example invocation and the expected count-summary file. Grouping labels does not establish that those labels are correct.
The wording deliberately describes a plan awaiting technical detail. It is not a finished installation section. A maintainer must supply the actual supported environment, invocation and observed example outcome before presenting those parts as tested. Do not turn a plausible command into a claim of successful execution merely to complete the README.
Make the example inspectable
For the actual project, show where the input comes from and where the output will be written. Use a small, permitted demonstration input that serves the first-use task. Do not require a reader to obtain private project data simply to understand how the software is meant to be used.
Explain the important output fields and one check the reader can perform. If the program reports category counts, the reader needs to know what was counted and how omitted or unrecognised values are represented. Those details must follow the implementation and its tested example, rather than a generic explanation of how counting ought to work.
State the scope of the verification. A demonstration completing in one recorded environment is evidence about that run; it is not evidence that every platform is supported or every research conclusion has been reproduced. Keep known limitations close enough to the example that a new user sees them before relying on the output.
Keep the README distinct from neighbouring documents
The Turing Way’s project-documentation chapter distinguishes a README from contribution guidance, a roadmap, a changelog, licensing information and software-citation metadata. Link to the actual relevant resources instead of asking a new user to infer those arrangements from an introduction.
A public repository does not by itself establish permission to reuse everything it contains. Describe the project’s actual licensing and material-access information without inventing terms or applying a familiar licence label from another project. Likewise, a roadmap item should remain identifiable as planned work rather than appearing in the list of supported features.
After files or behaviour change, check the first-use route again and update the associated repository version note. Keep any data-availability statement consistent with the actual example material and access conditions. The final README should let a newcomer understand the task, find a checked starting route and recognise what the example does not establish.
