The runbook aims to document all the Student Robotics specific information which a volunteer might need. This includes the historic context for the way that things are currently done, the reasons behind that approach, as well as the instructions on how to do things.
In that regard, the runbook aims to be descriptive rather than prescriptive. We are always open to new ways to do things, though by recording the reasons for our current approach we aim to avoid needing to rediscover that repeatedly.
For more detailed guidance for editors, please see our contribution guide.
The runbook aims to provide general information as far as our own specific information goes, so that it can always be a starting point for understanding. There are many cases where it should not contain the actual documentation:
- Information about Student Robotics' structure as a charity. This instead is documented by the trustees in the ops manual.
- Detailed information about internal (or external) tooling. These instead live with the tooling so that the runbook is not coupled tightly to the development of that tooling. Note: the runbook may contain guidance on our approach to using external tooling, or recipes for using tooling which are common to us but too specific for general documentation.
The runbook aims to be organised around the things it documents, rather than the organisational structure which may be responsible for that thing. This is a deliberate change from the previous structure, which had lead to a chicken-and-egg scenario of needing to know what something was and who was responsible for it and where the docs for it were in order to find the documentation for it. It is hoped that this approach will make the documentation more approachable to newcomers, for both reading and contributing.
It's worth noting that, as of late 2021, the runbook is still a way off achieving this aim as it contains considerable left-over structure & content from the previous documentation which it subsumed.
While the runbook contains documentation relevant to the activities of all SR teams, no one team owns it any more than any other volunteer. Instead the runbook aims to be a collaborative venture by all volunteers.
That said, it is expected that contributions to the runbook should seek input from volunteers with experience in the relevant area as part of their review process. In time, it is hoped that the runbook's review process will support this directly, perhaps through the use of GitHub's code owners feature.