-
Notifications
You must be signed in to change notification settings - Fork 0
Project Template
This is an example template wiki page for an RSE project. It is broken down into several sections:
This section is to give a broad overview of the project aims, along with a summary of the project agreement.
A summary of the initial aims of the project, i.e., is an web app to be developed? Is a pipeline being created for continuous integration? Is a code being ported to GPU? Of course often projects have flexibility built into them, but it is useful to see what the broad aims are.
Building from the broader project aims, it could be useful to know what has been agreed for the allocated funding:
- RSE time (e.g., 0.4FTE?)
- over what timescale is this project expected?
- are there smaller project aims that must be met?
This section is to list instructions on how a new RSE could get setup to begin developing on this project.
The structure of this section is dependent on the particular details of an individual project, but is supposed to sum how to get 'setup' with a project. For example, linking to external documentation with pointers to the most relevant sections (particularly useful if the documentation is very large and the RSE project only focuses on a small subset of the code base). Similarly, pointers for getting software setup on relevant systems, e.g., modules/environment to load on Hamilton/Bede/COSMA, or instructions on getting setup on a server or cloud system.
This is potentially not necessary, but for some code bases it can be useful to see an outline of the software structure, e.g., how the program may interface with a database, or the order in which certain components are run. However, this might not be needed for all projects.
This section will probably make up the bulk of a project page, and will probably consist of:
- useful links (e.g., documentation, tutorials, training materials, etc.)
- introductory material (e.g., code blocks to potentially explain how some APIs and libraries are used)
- outlines of the
An example subsection to list libraries used, e.g., why they are used; is versioning an issue
Another example subsection to list software tools used, e.g., testing, continuous integration, containerisation. These could just give a very brief overview of how they are used in this project, and then simply link to a more detailed wiki page in the Software Tools page.
As a project is coming to a close, it could be useful for an RSE to write a summary of the work, e.g.:
-
What were the primary technical challenges?
- Are these technical challenges relevant to other RSE projects (current/future), and if so, could further the RSE write more detailed material on best practice for overcoming these technical challenges?
-
Were there significant knowledge gaps?
- If there were knowledge gaps within the team, could this be rectified with training or this could be raised at an RSE catchup to see whether this knowledge gap needs to be filled
-
Were there non-technical challenges?
- This is quite
Then finish the documentation with a 'what next?' subsection, e.g.:
- is an individual RSE/the RSE team waiting on extra funding to start a next stage of the project?
- is the project simply changing hands for a new RSE to pick up
- was this project just a proof of concept for say a web interface, and there is a next stage that involves, e.g., building an app
- is this project focused on development, but the software is now moving into a 'maintaining' stage It is useful to give this context to know how the current project is finishing and whether it is remaining relevant to the team. This also fits with concept that RSEs can help improve the maintainability and sustainability of code, e.g., is an RSE going to be maintaining software developed during this code.
Finally, an RSE is welcome to extend this template as much as they want, but broadly the sections listed here should be viewed as a minimum.