This page is about writing documentation for tools we have. For safety (and insurance) reasons, almost every tool should have:
Usually, the 'tool owners', instructors, or most regular users of the tool are responsible for this. The good news is that making this shouldn't take long, and there are plenty of people to help you.
If you're reading this, there's a good chance you already have this. Usually, the tool owners are people who:
This is the most boring part, but is usually also the easiest. We have a generator for it, so you just need to edit some markdown:
./scripts/open.sh
. This should build a local copy of the documentation, and open the landing page for it../scripts/new-tool.sh "<tool name>" "<tool location>"
, ie ./scripts/new-tool.sh "Lathe" "Workshop"
. This should create a risk assessment and a syllabus for your tool, based off of a template, and print out their paths.risk-assessment.md
. To rebuild your local copy, run ./scripts/generate.sh "<tool name>"
to rebuild only your tool's documentation, or skip the tool name to rebuild everything.To write the actual content of your risk assessment:
To make this easier, you can look at other people and makerspace's risk assessments, for example:
If:
then you don't need this - delete the syllabus.md
file you generated in the previous step, and do the normal push to your fork & make a PR thing.
Otherwise, there needs to be some checklist for what people need to know before using your tool. This is true regardless of if the tool is access controlled or not.
You don't need to write a whole training course. Since the training will only ever be given by someone who knows what they're doing, you normally only need a list of headers with some reference information. Here are some known-good training syllabuses (shortest to longest), and their source code:
As well as the actual training documentation, we also generate a training card, which lets instructors keep track of a person's progress. Double-check that this looks OK too. (TBD: policy on when we have to get these signed, and when they're optional)
Once you're happy with your changes, push them up to your fork and make a pull request.
Wiki pages are where we put non-safety-critical stuff contributed by members. For convenience, you should link to the documents you made above, and list any model numbers, etc. Here's a template you can copy-paste:
^ [[https://edinburghhacklab.github.io/some/link|Risk assessment]] | [[https://edinburghhacklab.github.io/some/link|Training syllabus]] | ^ Model number | C6903-NICE | ^ Responsible people | <your names and/or discords> | ^ Manufacturer info | <link to manual, software, etc> |