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. In general, 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.
While a developer manual or programming guide, is a document that provides detailed information, instructions and guidelines specifically targeted at 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, implementing customizations, and effectively contributing 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.
Same as a software management plan, documentation is a living document and needs to been constantly reviewed and updated as the project progresses.
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.
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.