Every tool in the Toolbox is a small YAML file in the toolbox/tools/ folder. A build script turns these files into the tool pages, the overview tables, and the Tools for this step boxes in the chapters. You never edit those pages by hand.
If you are not comfortable with GitHub, open an issue with the tool’s name, website and the chapter where it helps, and an editor will add it.
Before you start¶
Check that the tool:
is relevant to AI in healthcare;
supports at least one FUTURE-AI principle;
is publicly available from its developers (free or paid);
is not already in the Toolbox.
1. Create the YAML file¶
Copy toolbox/TEMPLATE.yml to toolbox/tools/<id>.yml, where <id> is a short lowercase name such as fairlearn. The schema describes every field. The most important ones:
| Field | What to fill in |
|---|---|
summary, description | What the tool helps you do, in your own words |
type, format | The kind of tool, and its concrete form (e.g. “card game”) |
lifecycle, future_ai, audiences | Lifecycle phases, FUTURE-AI principles (at most three) and pathway audiences |
practical | Time, group size, facilitation, skills, cost and languages |
license | The tool’s licence, and whether we may copy its materials (rehost) |
passages | Where in the book the tool helps, with one sentence of explanation for each |
2. Link the tool to a passage¶
A passage is a section of a chapter where a Tools for this step box appears. Look for an existing passage first: search the chapters for toolbox/_generated/passages/ to see the ids in use, and add the id to your tool’s passages.
If the right section has no box yet, create a new passage. Choose an id of the form <chapter label>-<section>, and add this to the chapter, at the end of the section:
:::{include} ../toolbox/_generated/passages/design-stakeholder-engagement-methods.md
:::The box is generated from all tools that list that passage id.
3. Build and check¶
From the repository root, run:
make toolbox # validate the YAML and generate the pages
make serve # preview the bookmake toolbox stops with a clear message if a field is missing, a value is not allowed, a passage id does not exist in the book, or a passage has no tools. The same check runs on every pull request. Rerun make toolbox after each change to a YAML file.
4. Open a pull request¶
Describe the tool and why it belongs in the Toolbox, and link the issue that proposed it (Closes #<number>). An editor will check the facts and the licence before merging. The full process is described in Contributing.