Tool Documentation

This page is about writing documentation for tools we have. For safety (and insurance) reasons, almost every tool should have:

1. One or more tool owners, who have a good idea how it works & how to use it. These don't need to be the actual 'owners', if it's a long term loan.
2. A risk assessment, if it has any non-negligible risk. If you're not sure, ask!
3. A training syllabus, usually. You may be able to skip this
4. A wiki page, which lists all of the above

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:

• Have used the same/similar tools before
• Have at least some time and effort to teach others
• Know what they're doing

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:

1. Fork the edinburghhacklab/hacklab-training repository.
2. On a Linux machine (or one with Docker), clone your fork
3. Run ./scripts/open.sh. This should build a local copy of the documentation, and open the landing page for it.
4. Run ./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.
5. Edit the path ending in 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:

1. Make a list of everything that could go wrong, that could harm a person or the environment. The things might happen because of:
   1. The tool being broken
   2. The tool being misused
   3. Bad luck
2. Decide on its severity: how bad it is if it happens, in the worst case.
   1. If someone could die or lose a limb, its high
   2. If someone could give themselves injuries lasting weeks to months, its medium
   3. If someone could give themselves a scrape or bruise, its low.
   4. If in doubt, round up.
3. Decide how to mitigate it.
   1. This could be by keeping it in a certain environment, maintaining it properly, etc.
   2. Often, this involves 'the user will not do X'
4. Decide how likely it is to happen, bearing in mind the mitigation you just decided on.
   1. This is quite subjective, so consider getting a 2nd opinion
5. Decide on the overall 'risk rating'
   1. There should be a comment on how to decide this in the template.
6. Put it in the template, rinse and repeat until you run out of horrible accidents to imagine.

To make this easier, you can look at other people and makerspace's risk assessments, for example:

• Makespace cambridge
• Southampton makerspace
• NottingHack

If:

1. There's no risk assessment, or the risk assessment doesn't say “users will do <X>” AND
2. The tool has a manual, and we use it like in the manual

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:

1. Sander, source
2. Welder, source
3. CNC Router, source

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> |