Software Research Documentation and Accounting Guide

Effective software research documentation records what a tool does, who it serves, how to install and use it, and which versions of code and data support the research. Start with a lean README, then add user guides, developer references, and maintenance instructions as the project grows. A UK Research Software Survey of 1,000 randomly chosen researchers found that more than 90% considered software important to their research, while about 70% said their work would not be possible without it.

Useful documentation connects software use to reproducible results through accessible code, data, methods, tests, and version history. Include a “how-to-cite” section when citation is wanted, and organize materials around the needs of users, developers, and maintainers. GitHub can centralize code and documentation, while Zenodo supports deposits of software, datasets, and other research outputs.

Start Software Research Documentation with a Lean README

Start with a lean README that explains the software’s purpose, intended audience, installation, usage, and relevant code and data. Expand that record as requirements stabilize, rather than waiting until you can build a complete documentation system or treating the initial README as the finished documentation.

Planning begins with the audience: who needs this information, what do they want from it, and could another format communicate it better? Answers should shape both the content and its depth. Beginner users need different explanations from experienced researchers, while developers and maintainers need information that supports extending and sustaining the software.

Define the purpose. Explain what the software does, why it was written, and which research needs it addresses. Identify the intended users so readers can judge its relevance to their work.
Describe installation and setup. Provide instructions for getting started, including configuration and usage requirements. Clarify how the software works with the data and other tools its audience uses.
Show how to use it. Add a getting-started snippet or tutorial that helps readers apply the software. Keep introductory instructions focused, with reference documentation available for more detailed use.
Locate the supporting materials. Point readers toward the relevant versioned code, data, tests, and additional analyses. Use descriptive names and explain repository contents so those materials are understandable alongside the usage instructions.
Grow the documentation incrementally. Invite contributions and add detail as requirements become more stable. Move toward separate user guides, API references, or maintenance instructions when the project’s needs justify them.

Scope the work around the time available and the expected maintenance period. Documentation needs also depend on software complexity, the field of use, and users’ experience. A small starting document can remain useful without trying to serve every audience equally, provided its content develops with the project.

Organization matters as the README grows. Separate core code, test scripts, data, and documentation within the repository, using clear directories and descriptive names. Supporting README files can explain individual areas, while a navigable documentation website can hold longer setup instructions, examples, troubleshooting guidance, and reference material.

Maintenance should preserve the connection between instructions and software evolution. Reflect clear versioning in documentation through a changelog, and use repository history to track changes. Contributions can extend the record as the software develops and audience needs become clearer.

From 2009 to 2013, in the Dayton suburbs, I handled office and maintenance coordination at apartment properties and explained lease fees, deposits, and move out deductions for about 40 move outs a year, which taught me that a missing instruction becomes somebody else’s expensive scavenger hunt. For the Lean README in software documentation, name the purpose, intended users, setup, and first use, then point to fuller material rather than impersonating an entire filing cabinet.

Build a Research Software Inventory Around Audience Needs

Organize a research software inventory by the people who need its documentation: users, developers, and maintainers. Match each audience to the materials that help them use, extend, or sustain the software, rather than treating documentation as a single undifferentiated record. Planning should account for what those readers want, their experience, the time available for writing, and how long the project will be maintained. Different audiences need different levels of explanation.

Users need to understand exactly what the software does, how it works, and whether it can work with their data and other tools. Tutorials, user guides, getting-started snippets, and reference documentation serve those needs in different ways. Beginner guidance should differ from material aimed at experienced researchers or Research Software Engineers. Hands-on instructions can lower onboarding barriers, while conceptual explanations provide the requirements, design, and architecture context that supports understanding of the software.

Documentation Area	Minimum Materials	Primary Audience
User documentation	User guides, tutorials, getting-started snippets, reference documentation	End users
Developer documentation	Code comments, API documentation, requirements, architecture, design documentation	Developers
Maintainer and governance records	Development workflows, code of conduct, LICENSE, CITATION file, changelog	Maintainers and contributors
Reproducibility materials	Code, applicable raw data, additional analyses, tests, version-controlled history	Readers and future researchers
Citation information	How-to-cite section, comprehensive user documentation	Paper authors and software users

Developers need documentation that supports extending the software and understanding implementation choices. API references should explain key functions, classes, and modules; design documentation can capture the reasoning behind particular decisions. Comments are most useful when they explain why something happens, rather than merely repeating what the code does. Requirements and architecture records provide higher-level context, while tests can act as functional specifications, especially when development follows a Test-Driven Development approach to implementing features.

Maintainers need records of development workflows and the rules that support collaboration. Contribution processes, coding standards, and testing procedures belong in the documentation when a project invites contributions. Governance materials can include a code of conduct, LICENSE file, and CITATION file, alongside a changelog that reflects clear versioning. Responsibility may overlap: an individual can act as both a Research Software Developer building features and a Research Software Engineer handling infrastructure, maintenance, and development rules.

Classification should also reflect purpose, not just job titles. Conceptual material explains requirements and design; hands-on material helps people perform tasks; reference material supports looking up technical details. Reproducibility records serve readers who need to verify or build on findings, while citation guidance supports authors who want to acknowledge software. Keep these audience needs visible as the project evolves, and allow others to contribute documentation as requirements become more stable and maintenance needs change.

Quantify the Software Record Your Paper Needs

The observed record burden is 6.5 distinct software mentions for each Nature paper that mentioned software. A paper’s software record should account for every distinct software item named in its research narrative, rather than treating software as a single background resource.

An examination of 40 Nature papers found that 32 mentioned software. Those 32 papers contained 211 mentions of distinct software, so the calculation begins with 211 distinct-software mentions divided by 32 papers that mentioned software: 211 / 32 = 6.59375.

Rounded to one decimal place, 6.59375 becomes 6.5 software mentions per paper. That figure gives a concrete planning benchmark: a paper that mentions software may need records for several separate tools, each with documentation suited to its domain, role, purpose, and type.

Counting software mentions also helps match documentation to the people who need it. User documentation supports people applying software and knowledge, while developer documentation supports expansion of tools and extension of knowledge; tutorials and how-tos support broader use, including by non-researchers.

Connect Software Version Reporting to Repository History

Connect software version reporting to a version-controlled repository, and reflect version changes in a changelog. Separate code, tests, data, and documentation into clearly named directories so readers can locate relevant materials and understand how the software has evolved. Together, these records support collaboration and help researchers identify the code and supporting materials associated with their work.

Version control maintains a history of software evolution rather than presenting code only in its current state. A changelog complements that history by making version changes part of the documentation readers can consult. Keep the changelog connected to the software’s documented versions, giving readers a clear route between information about changes and the repository record. Clear versioning belongs in the documentation, not just in the development workflow.

Repository organization provides the other part of that route: an understandable place to find each material. Readers should be able to distinguish the software itself from the materials that explain, test, or support its use. Logical separation also supports a navigable repository instead of leaving those different materials mixed together.

Directory README files can explain their contents and provide instructions for using them. Within that structure, code comments and docstrings supply detail close to the implementation, while API references describe key functions, classes, and modules. Comments should explain why a choice was made when its purpose is not obvious, rather than merely restating what the code does. Design documentation can preserve the reasoning behind implementation decisions.

Tests provide another useful record. Alongside version-controlled code and documentation, test scripts help communicate intended functionality. Supplementary materials can hold raw data, code, and additional analyses that do not fit in a paper. Access to these materials helps readers reproduce results, verify findings, and assess their validity and reliability.

GitHub can provide a central location for sharing this organized code and documentation. Issues and discussions support collaboration and problem-solving around the repository. For a more navigable documentation interface, a dedicated website can present setup instructions, configuration, examples, and code-and-data usage guidance alongside API references and troubleshooting information.

Document Code Dependencies and Usage Requirements

Document code dependencies and usage requirements through installation instructions, setup and configuration guidance, and explanations of how the software works with users’ data and other tools. Pair those practical instructions with API references and comments that explain implementation choices. Together, these materials should help readers understand both how to use the software and how its behavior supports their research question.

Setup guidance should explain how to install and configure the software, with usage instructions that readers can follow. Getting-started snippets and examples can support those instructions without requiring beginners to work through a full technical reference first. Keep the explanation focused on what users need to do, while providing reference documentation for readers who need more detail about particular operations.

Compatibility explanations should address whether the software works with the reader’s data and other software. Rather than describing a feature only in implementation terms, explain what it does and what research need it serves. Show how code and data are used together through examples, so readers can relate the instructions to the work they want to carry out in practice.

User guides and how-tos serve a different purpose: helping people apply the software to their work. Distinguish these tasks when writing documentation, so an explanation intended for someone extending a tool does not substitute for instructions intended for someone simply using it.

Design documentation can expand on the reasoning behind particular choices, while requirements and architecture descriptions provide higher-level context. Use comments and docstrings with automatic documentation tools where appropriate, alongside explanations of why a feature exists and how it answers research needs.

Troubleshooting guidance and explanations of common errors belong alongside setup, configuration, and usage instructions in a human-readable, navigable documentation interface. Dedicated documentation websites can bring these materials together with examples and API references. Match the depth of explanation to readers’ experience: beginners need different guidance from experienced researchers or Research Software Engineers, and beginner-level how-tos can help lower onboarding barriers.

Support Reproducibility with Code, Data, and Tests

Make supporting code, raw data where applicable, additional analyses, and tests accessible alongside usable documentation so readers can reproduce results, verify findings, and build on the work. Reproducible research software practices connect these materials to the methods they support, giving readers a way to examine the work beyond the account presented in a paper. Accessibility matters because supplementary materials can contain evidence that the main text cannot accommodate.

Without access to those materials, readers may struggle to assess the validity and reliability of the findings. Treat these supporting records as part of the explanation of the research, rather than leaving the paper to carry every methodological detail on its own.

Tests add another way to understand the software’s behavior. Beyond that, tests can also clarify the software’s behavior alongside prose descriptions. Include test scripts with the supporting code so readers can examine those specifications as part of the research record. Continuous integration can automate testing and support code quality and reliability.

Usable documentation helps readers move between the scientific question, the software, and the supporting evidence. Explain what needs to be done to answer the research question and how the relevant features implement that work. Examples and user guides can help readers apply this knowledge, while troubleshooting guidance and descriptions of common errors support practical use of the shared materials.

Sharing also requires a discoverable place to reach the supporting records. Zenodo, operated by CERN, accepts datasets, software, and other research outputs. Another option is the Open Science Framework, a free, open-source platform from the Center for Open Science that supports the research lifecycle. Choose documentation that helps readers find and use the deposited materials, with a human-readable, navigable interface rather than relying on code and data alone.

Plan the depth of this documentation around the audience, software complexity, and expected maintenance period. Beginner-oriented how-tos can lower onboarding barriers, while experienced researchers may need reference material to extend the work. Expand the explanation as requirements stabilize, and allow others to contribute. Together, accessible evidence, tests, and audience-appropriate guidance support reuse while helping future researchers understand and build on the findings.

Explain How to Cite Research Software

Explain how to cite research software in a dedicated “how-to-cite” section, backed by comprehensive user documentation. Include a CITATION file among the project’s maintainer records so citation guidance has a place alongside development workflows and other project documentation. Together, these materials address citation as part of maintaining the software, rather than leaving recognition of the work separate from the information people need to use it.

Readers seeking citation instructions have a different immediate need from users seeking a tutorial or developers consulting an API reference. Keep the how-to-cite section focused on citation guidance, while allowing user documentation to explain the software and its use. Comprehensive documentation remains part of the recommendation because citation instructions are not a substitute for helping people understand the tool. Good documentation can contribute to greater citation and recognition of research software.

JOSS software-publication standards can provide a starting point when developing a project’s citation practices. For a broader overview of the considerations involved, consult the Software Citation Principles paper. Use these resources to inform the guidance maintained with the project. Rather than treating citation as an isolated publishing task, place it within documentation planning that accounts for audience needs, available writing time, and the expected duration of maintenance.

Sharing platforms serve a related but distinct purpose: they provide places for research outputs and project materials, while a how-to-cite section supplies citation guidance. Neither role should be confused with writing the project’s own citation instructions.

Maintainers can treat the CITATION file as part of the documentation that supports sustainable collaboration, alongside a LICENSE file, code of conduct, and development workflows. Citation guidance belongs within that broader record, but it has its own purpose: helping software users and paper authors acknowledge the work. As documentation grows from a lean README, retain an identifiable how-to-cite section rather than blending citation instructions into general descriptions of sharing platforms or project administration.

Maintain the Record and Separate Financial Accounting

Keep research software documentation useful by maintaining contribution procedures, testing guidance, and development workflows as the project evolves. Plan that work around audience needs, available writing time, and the expected duration of maintenance, with the documentation focused on software use, development, and support. A lean record can grow as requirements stabilize; its scope should reflect the software’s complexity and the needs and experience of the people who depend on it.

Contribution guidance should explain the process for contributing, the coding standards contributors should follow, and the testing procedures used by the project. Developer documentation can support those instructions with requirements, architecture, and design explanations. Maintainer documentation serves a different purpose: it records development workflows and social expectations, including a code of conduct. Together, these materials support collaboration while giving contributors guidance on both implementation work and participation in the project.

Testing guidance belongs alongside development procedures rather than being treated only as supporting material for a paper. Tests can act as functional specifications, particularly in Test-Driven Development, while continuous integration can automate testing and deployment to support quality and reliability.

Maintenance planning should recognize that different people need different records, even when one person holds several roles. Research Software Engineers are responsible for infrastructure, maintenance, and development rules, while Research Software Developers build features for specific research questions. Users need guidance that helps them carry out computer-aided work. Organizing documentation around those responsibilities helps distinguish instructions for using a tool from explanations needed to extend it or sustain its development.

Documentation should remain open to contributions and increase as the project’s requirements become more stable, with a navigable documentation site bringing workflows, troubleshooting, common errors, and contribution information together. Keep the maintenance record centered on those practical tasks. Clear guidance supports continued use and extension of the software, with documentation effort matched to the project’s audience and expected maintenance period.

Frequently Asked Questions

What Should a Research Software README Include?

A research software README should explain what the software does, who it is for, and how to install and use it. Include enough information for users to understand whether it works with their data and other software. Start with a lean overview and expand it as the project and its audience require.

How Much Documentation Does a Small Research Project Need?

The appropriate amount depends on users’ needs and experience, software complexity, available writing time, and the expected maintenance period. A lean README can be the starting point rather than a complete documentation system. Add documentation incrementally as requirements stabilize, and allow others to contribute.

How Should Software Versions and Changes Be Documented?

Use version control to preserve the history of software development and support collaboration. Documentation should reflect clear versioning, with a changelog recording changes. Keep the relevant versioned code and data accessible to support reuse and reproducibility.

Where Should Software Citation Instructions Go?

Include a “how-to-cite” section in the project documentation if you want the software to be cited. A CITATION file can also form part of the project’s maintainer documentation. Comprehensive user documentation should accompany citation instructions so readers can understand and use the software.

What Supporting Materials Help Readers Reproduce Software-Based Results?

Supporting materials can include code, raw data where applicable, additional analyses, and methods needed to understand the work. Tests and version-controlled repository history also help researchers evaluate and build on the software. Provide setup, configuration, and code-and-data usage instructions so readers can put those materials to use.

Does a Research Software Inventory Determine Financial Accounting Treatment?

Research software documentation serves a technical purpose: recording what software does, how it is used, and which versioned code and data support the work. Its maintainer records can include LICENSE and CITATION files, development workflows, and a changelog, supporting maintenance, attribution, and version clarity.

Start with documentation that helps someone understand and use the software, then expand it as the work develops. Match user guides, developer explanations, and maintainer records to the people who need them. Keep code, data, methods, and version history accessible enough to support reproducibility, and explain how to cite the software when citation is wanted. A lean beginning is compatible with long-term care: documentation can grow alongside stable requirements, new contributors, and a broader audience.

References

Evidence for the importance of research software, Research Software Alliance, researchsoft.org
What are best practices for research software documentation?, Institute for Research Software, software.ac.uk
Effective Documentation of Research, Scaling Science, developmentseed.org
Ten Essential Guidelines for Building High-Quality Research Software, arXiv, arxiv.org
Documenting research software in engineering science, Scientific Reports, nature.com
Software Documentation, EBSCOhost, ebsco.com

Sources read in September 2026.