A2: Terms of Reference Guidelines
The Terms of Reference (ToR) document is created based on initial contact with the potential partner(s). It can be produced by any member of the Research Software Engineering (RSE) team, though it will usually be created by the team member occupying the Research Software Analyst (RSA) role. It is not intended to be a customer facing document but rather a record for the RSE team of the main requirements identified in the project and it will be used for regular referral during the early stages of the project.
If the RSE team choose to adopt a Project Planning stage the information in this document can be used to inform decisions about whether or not the research fits well with your institutional goals and your team remit. It may also be a helpful early indicator of feasibility and proves to be very useful as reference documentation in the absence of team members who had initial contacts with partners or when substantial time lapses between follow up meetings with partners. The document is used also to record preliminary discussions on research data management as part of the background context for the project, the requirements themselves, the risk and issues connected to the project and/or the technical considerations.
At a minimum it should cover the high-level concepts in sufficient detail to enable discussion of the appropriate technical and management strategies with entire RSE team at the Feasibility stage.
Although each section of the ToR is discrete there will inevitably be overlapping details and priorities between the sections.
This section of the ToR is for recording an outline of the high-level concept(s) of the research and outputs being proposed. It presents an opportunity to gain an understanding of the goals of the research and the motivations of the team involved and value judgements should be avoided at this stage.
The matrix below offers some prompts and key questions for completing this section effectively. It is not intended to be exhaustive but instead aims to stimulate conversation during the initial meetings.
| Example questions and prompts | Check |
|---|---|
| What is the core idea, vision, and context? | |
| What are the research questions partners aim to tackle with this digital project? | |
| What knowledge domains are being explored? | |
| What disciplines does the research draw on? | |
| What data sources (type, format and size) are being considered for use? | |
| Which established methodologies will be used? | |
| What skills are needed within the project team? | |
| What concrete outputs are anticipated to come from the research? | |
| How is the project team structured in terms of institutions, responsibilities and leadership? | |
| What other organisations are involved? | |
| What level of funding is secured or targeted? | |
| Who are the intended audiences for the project? | |
| How will the intended audiences interact with the research outputs? | |
| What is the time span for the project? Submission deadlines? Commencement? | |
| What expectations are there for the project beyond the funded period? | |
| What sort of archiving should be planned for? | |
| Prompts for further feedback after the meeting: | |
| Ask the team to describe a number of user journeys through the project outputs | |
| Encourage them to provide a 1 or 2 sentence elevator pitch to focus their vision |
This section provides a space to record information that can feed into decision making during the Project Planning stage.
The matrix below offers a selection of helpful prompts which can guide the RSE team when making a decision about whether to proceed to the Feasibility stage.
| Example questions and prompts | Check |
|---|---|
| Have the RSE team had previous experience of working with this project team or members of the team? | |
| Will the project team fully engage with the SDLC processes? | |
| What previous work (if any) is being built upon? | |
| Has previous work in this area failed to produce quality research? If so, why? | |
| Is there an existing resource upon which this new work depends? | |
| What distinguishes this research as particularly ambitious or innovative? | |
| Does the project align with current internal goals and strategies? | |
| Does the project align with internal research interests? | |
| Does the RSE team have access to the necessary expertise to fulfil the project requirements? | |
| How amenable to digitisation or to computational processing are the data sources being proposed? | |
| Are there sample data to access and assess? | |
| Where are the datasets hosted if they already exist or where is the project team expecting to host them, and for how long? | |
| How amenable to archiving is the project being proposed? | |
| Are the ambitions of the team realistic? | |
| Does the project present ethical concerns? |
This section is used to summarise the main deliverables of the project. Although prioritisation might not be practical or desirable at this stage, it is worth attempting to identify those outputs that, if not delivered, would compromise the rationale of embarking the project. All requirements should be considered, functional and non-functional, from infrastructure upwards.
It is crucial for requirements to be expressed in a common language that is both understandable to partners and operationalisable by the RSE development team that will need to further translate them into actionable tasks after Feasibility and when the foundations or evolutionary development phases for that project become active.
Must Have requirements are those that would compromise the rationale of the project if not delivered. Test whether the core goals of the research can still be met, even at considerable inconvenience, if this requirement were not fulfilled.
Should Have requirements are those that would significantly improve workflow and reduce inconvenience for users attempting to achieve a core goal of the research. These requirements, if not directly applicable to a particular Must Have requirement, may be of secondary importance to the core research goals.
Could Have requirements are those that provide marginal improvements in workflow and may be aesthetic or of tertiary importance to the core research goals.
Won’t Have requirements are those that are aspirational in nature but present significant technical and practical obstacles given the timeframe and funding proposed or allowing for the current technical landscape. They may present very marginal benefits to the overall project goal or may be more suited to follow on research pending the successful completion of the initial project.
Copyright Agile Business Consortium Limited.
The matrix below offers some prompts and key questions for effectively completing this section. It is not exhaustive, but aims to stimulate internal conversation in a productive way.
| Example questions and prompts | Check |
|---|---|
| Will the project require dedicated infrastructure? | |
| What key services will any dedicated infrastructure need to provide? e.g. Image server, Web server, High Powered Computer etc. | |
| How much storage is likely to be required for any source materials? | |
| Does the project require a website? If so, what is its primary purpose? e.g. Dissemination, Research platform etc. | |
| Does the project require bespoke data structures? If so, which forms are most suitable? e.g relational database, graph database, XML etc. | |
| What kind of data (type, format and size) is the project team expecting to create and/or process? | |
| Are there domain specific conventions and standards that must be observed, such as metadata standards formats, ontologies etc? | |
| What are the design requirements of the website? e.g. a landmark resource with a strong brand identity, or limited brand identity with a focus on specialist functionality, or a completely standard backend interface which will only ever be used by the project team etc. | |
| For a web resource or stand-alone piece of software, what are the key user interactions that should be possible? e.g. textual search, faceted search, free browsing, data entry, moderated contributions from the public, forums, map visualisations, data visualisations, API etc. | |
| Will the resource draw upon third-party data or resources? Are there issues of copyright and licensing to consider? | |
| Will there be consultancy products? e.g. reports, scoping documents, design guidelines, etc. | |
| When this list of requirements is completed, attempt to prioritise the items using the MoSCoW classification described above |
This section attempts to direct early planning decisions toward possible difficulties and complications with the research project. Anything which represents security, legal and reputational risk, or complicates achieving a successful outcome should be considered here.
The matrix below offers some prompts and key questions for effectively completing this section. It is not exhaustive, but aims to stimulate internal conversation in a productive way.
| Example questions and prompts | Check |
|---|---|
| Can the RSE team expect reasonable and equal collaboration with the project team and its members? What can be implemented to mitigate any identified risks? |
This section should summarise the technical constraints of the project.
| Example questions and prompts | Check |
|---|---|
| Does the potential partner require that a particular software solution is used? If so, why? | |
| Are there issue of compatibility with the RSE team software stack and workflows? | |
| Does a finished resource need to be hosted externally? | |
| What level of use/traffic should be planned for? | |
| Are there data standards, either de facto or de jure, that the resource must comply with? What are they? | |
| Are data input or export in a particular formats expected? What are they? | |
| Is data versioning expected? |
In this section information about the expected research outputs for the project should be included.
| Example questions and prompts | Check |
|---|---|
| Are any of the digital products to be considered as research outputs? | |
| Is the RSE team expected to contribute to any other research outputs such as conference contributions or academic articles on the project? | |
| Is the project producing other research outputs which rely on the RSE team digital products e.g. monograph based on data evidence and processing workflows? |
This section encourages consideration of the likely impact of the research project on the relevant research community as well as the reach and significance of the project for other beneficiaries (e.g. museums and archives, schools, indigenous communities, particular groups of stakeholders, the public etc.) and may help to inform a collective decision about whether or not the RSE team should pursue the project.
As is the nature of research projects, many months may pass between meetings or waiting for the right funding call to come along. Staff may change, or similar projects may crop up. Researchers approaching the RSE Lab will often have had time to reflect on many different approaches to their research questions and this section can be a valuable way of keeping up with the state-of-the-art in many different domains.
| Example questions and prompts | Check |
|---|---|
| What other online resources most closely represent the aims of or inspiration for this project? | |
| What research papers or other publications might help the non-domain expert become acquainted with the research topic? |
Typically the stage following the preparation of the ToR would be to prepare;
- Feasibility report (in the case of new projects)
- Statement of Work (in the case of extant projects requiring maintenance or new development)