Documentation
A software management plan should include explanation of how the research software will be documented as well as the types of documentation that will be created. A research software project should include manuals for both users and developers.
A user manual, also known as a user guide or instruction manual, is a document that provides instructions, information and guidance on how to use the software. User manuals are typically written in a clear and concise manner, using language that is easy for users to understand. They serve as a reference guide that users can consult whenever they have questions or need assistance while using the software. It is designed to assist users in understanding the features, functionality and operation of the software.
In contrast, a developer manual or programming guide is a document that provides detailed information, instructions and guidelines specifically targeted to other research software developers who may be involved in the development, customization or future maintenance of the software. A developer manual aims to provide comprehensive technical documentation that assists developers in understanding the software’s internals, and how to implement customizations and contribute to the development process. It serves as a valuable resource for maintaining code consistency, collaboration among developers and ensuring the long-term sustainability of the software project.
Like a software management plan, user and developer documentation are living documents and need to be reviewed and updated as the project progresses, ideally as part of the development process.
Version Control Protocol
A software management plan should specify the version control system that will be used to manage the research software source code and track changes. Furthermore, it should describe the project’s workflow and branching strategy. A branching strategy dictates how branches in the project are created, managed and merged within the code repository hosting the project. It defines the structure and flow of code changes (code review and approval e.g.) throughout the development lifecycle. This protocol gains importance as the number of developers and contributors to the project increases.
Overall, version control provides a systematic approach to managing the development, collaboration, documentation, and long-term maintenance of research software. It fosters transparency, reproducibility, and efficiency, allowing researchers to focus on their work while maintaining a reliable and accessible codebase. For more information about a version control workflow, please visit our other learning module on Git repository management services.