Write a research-software problem report that separates observation from diagnosis
Write a factual software problem report with observed behaviour, expected behaviour and an honest reproduction record.
About 5 min read · Allow extra time for the practical checks
Start with the software task, the steps you actually took, the result you expected and the result you observed. Keep your explanation of the cause separate from that record. A precise report can help a maintainer investigate a problem even when you cannot yet establish whether it comes from the program, its input, the environment or your understanding of the instructions.
This guide concerns writing an ordinary problem report. It does not diagnose software, execute a demonstration or certify the validity of research output. Use the project’s designated support route and any applicable rules for sharing material.
Establish what you can report
Check the project’s instructions and existing reports before opening a new one. Use its requested template when available. Describe the relevant software release and environment from records you can inspect; do not fill missing fields with the current version number merely because it appears on the website.
GitHub’s issue quickstart, checked on 2 November 2026, recommends a descriptive title and a useful account of the issue. Its bug-report example distinguishes reproduction steps, expected result and actual result. That is guidance for providing information, not proof that every unexpected result is a defect.
A title such as “Import stops after selecting the demonstration CSV” gives a reader a starting point. “Broken software” leaves both the action and the observation unclear. Name the affected task before adding a theory about its cause.
Work through an original fictional report
All software names, actions and messages in this exercise are invented teaching material. No program was run and no actual defect or research result is represented.
Imagine a fictional teaching application, Table Lantern. A student’s draft report says: “The new importer is corrupting my study because it cannot read the file.” The student’s fictional notes describe something narrower: opening the supplied demonstration CSV in release 0.8 causes an import window to display a missing-column message. The student has recorded one attempt and has not inspected the cause.
| Part of the fictional report | Proposed wording | Boundary of the statement |
|---|---|---|
| Task | Import the demonstration CSV supplied with release 0.8 | Identify the actual example file before using this wording in a real report |
| Action | Open the importer, select the example file and choose the import action | Include the real sequence rather than a guessed command |
| Expected result | The example instructions led me to expect the demonstration table to load | Point to the relevant instructions in the real report |
| Observation | The window displayed “Required column not found” and no table appeared | Invented message for this exercise; quote an actual message accurately |
| Frequency | Recorded on one attempt | Does not establish repeated reproduction |
| Cause | Not established | Does not demonstrate corruption or a fault in a particular component |
A proposed opening could read:
In this fictional example, Table Lantern 0.8 displays “Required column not found” after the supplied demonstration CSV is selected for import. The example instructions led me to expect the demonstration table to load. I have recorded one attempt; I have not established the cause.
The revised account is more useful because a maintainer can see the discrepancy without accepting the student’s diagnosis. For a real report, replace every teaching detail with checked observations and supply the relevant environment information. Keep an unverified field visibly unresolved.
Make the supporting material usable
Benjamin C. Haller’s guidance in PLOS Computational Biology, checked on 2 November 2026, discusses reporting channels, relevant context, concise descriptions and examples that help a developer reproduce a problem. It distinguishes the occurrence from the reporter’s expectations and explains why reducing an example can make investigation easier.
For your report, identify the input, settings, relevant output and environment needed to understand the observation. Preserve exact error wording where it matters. Describe what you tried and what changed, rather than saying that you tried everything. If the problem occurred only once, say so; if you recorded repeated attempts, report the observed pattern without inventing a success rate.
Share only material you are permitted to disclose. Check attachments, paths, screenshots and logs before sending them. Removing identifying details can change an example, so do not call a substituted input a reproduction unless that behaviour has actually been checked. An unresolved sharing constraint should remain visible rather than being concealed by a plausible-looking replacement.
Keep follow-up evidence separate from the original observation
When a maintainer requests a check, record its actual outcome and the environment used. An investigation step that was suggested is different from one that you performed. A workaround that lets a window open does not by itself establish that the original research output is valid.
If your understanding changes, add a clear follow-up explaining which earlier statement needs correction. For example, a newly located instruction might change the expected behaviour while leaving the original observation accurate. Keeping those two parts separate makes the report easier to interpret.
The README guide helps inspect the documented first-use route. The software-citation guide helps retain the identity of a release used in the work. Finish the problem report by checking that its title, observations, attachments and unresolved questions describe the same event.
