Dev

.github/workflows/lint_alt_text.yml

@@ -0,0 +1,23 @@
+name: Check Alt Text
+
+on:
+  push:
+    paths:
+      - '**.qmd'
+      - 'lint_alt_text.py'
+      - '.github/workflows/lint_alt_text.yml'
+  pull_request:
+    paths:
+      - '**.qmd'
+      - 'lint_alt_text.py'
+      - '.github/workflows/lint_alt_text.yml'
+  workflow_dispatch:
+
+jobs:
+  check-alt-text:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check images for alt text
+        run: python lint_alt_text.py

CONTRIBUTING.md

@@ -157,3 +157,41 @@ To delete the image:
 ```{.bash}
 sudo docker image rm -f desrapbookdocker
 ```
+
+## Accessibility
+
+Quarto's supported accessibility checker `axe` is not used because it is difficult to read, and it mostly flagged things that cannot be changed (i.e., Quarto defaults and built-ins). As such, other approaches are used.
+
+### `lint_alt_text.py`
+
+A Python script is provided which checks for alt text. It supports patterns:
+
+* `![alt-text](fig.png)\` (backslash required for it to use caption as alt-text too).
+* `<img src="fig.png" fig-alt="alt-text">`
+* `![](fig.png){fig-alt="alt-text"}`
+
+To run the script:
+
+```{.bash}
+python lint_alt_text.py
+```
+
+This is configured to run via GitHub actions - see `.github/workflows/lint_alt_text.yml`.
+
+## Findability checks
+
+To support the FAIR principles for training materials, we keep a light-weight record of how easy it is for learners to discover the DES RAP Book via web search and chatbots. This helps us see whether changes to the site or metadata (for example, adding structured metadata or registering in training registries) actually improve real-world discoverability.
+
+If you’d like to help with this, please see `findability_checks.md`. That file explains:
+
+- Which example queries to use.
+- Where to run them (e.g. search engines, chatbots).
+- How to record the results in the simple log.
+
+You are welcome to run these checks occasionally, for example:
+
+- After major changes to the site or its metadata.
+- After registering the resource in a new training registry.
+- Or just periodically (e.g. once or twice a year) as part of general maintenance.
+
+Even occasional contributions to the findability log are helpful for tracking whether learners can still easily find the resource over time.

_quarto.yml

@@ -38,8 +38,11 @@ website:
             href: pages/intros/rap.qmd
           - text: Intro to FOSS
             href: pages/intros/foss.qmd
+      - text: Impact
+        href: pages/impact/impact.qmd
     right:
       - icon: github
+        text: "GitHub"
         href: https://github.com/pythonhealthdatascience/des_rap_book
   announcement:
     dismissable: false

findability_checks.md

@@ -0,0 +1,54 @@
+# Search and chatbot findability checks
+
+This page documents how we (lightly) test how easy it is for learners to find the DES RAP Book using search engines and chatbots.
+
+## How we test findability
+
+### 1. Queries we test
+
+We use a short list of queries that a typical learner might use when looking for this kind of resource. For example:
+
+- `reproducible discrete-event simulation book`
+- `DES RAP Python`
+- `DES RAP R`
+- `reproducible analytical pipeline discrete event simulation`
+- `healthcare discrete-event simulation reproducible training`
+
+These queries can be adjusted over time if we learn new phrases that learners commonly use.
+
+### 2. Where we test
+
+We currently test:
+
+- A general web search engine (e.g. Google) in a private/incognito window.
+- One or more chatbots (e.g. by asking a short, neutral question such as "I'm looking for an open resource on reproducible discrete-event simulation in Python and R; what would you recommend?").
+
+### 3. How we record the results
+
+For each query, we:
+
+* Note the **date** of the check.
+* Record the **search engine or chatbot** used.
+* Record whether the DES RAP Book appears on the **first results page**, and, if so, its approximate **position** (e.g. "#1", "#3", "not in top 10").
+* Optionally add brief **notes** (for example, "Zenodo record appears first; website second").
+
+We keep a simple log below to track changes over time.
+
+## Findability check log
+
+### Web search engine checks
+
+| Date | Name | Search engine |  Query | Result position | Notes |
+| - | - | - | - | - | - |
+| 3 Feb 2026 | Amy | Google | reproducible discrete-event simulation book | #1 (DES RAP Book GitHub), #4 (Mention from HSMA Little Book of DES) | - |
+| 3 Feb 2026 | Amy | Google | DES RAP Python | #1 (DES RAP Book GitHub), #2 (pydesrap_mms GitHub), #3 (DES RAP Book Zenodo), #6 (pydesrap_stroke Zenodo) | - |
+| 3 Feb 2026 | Amy | Google | discrete event reproducible | #7 (DES RAP Book Zenodo) |
+| 3 Feb 2026 | Amy | Google | discrete event python training | Not on first page |
+
+
+### Chatbot checks
+
+| Date | Name | Chatbot | Prompt | Mentioned DES RAP Book? | Notes |
+| - | - | - | - | - | - |
+| 3 Feb 2026 | Amy | Perplexity | "I want to build reproducible discrete event simulation model in Python or R. Do you have any training materials you'd recommend?" | Yes | First result is book, second result is the example models. |
+| 3 Feb 2026 | Amy | ChatGPT | "Please suggest training materials for how to write good discrete event simulation models in r" | Yes | 5th recommendation | 

index.qmd

@@ -27,7 +27,28 @@ format:
       }
 </style>
 
-<div class="h2-tight"></div>
+This open book is a self-paced training resource that teaches you how to design, implement, and share discrete-event simulation (DES) models in Python and R as part of a reproducible analytical pipeline. It combines a step-by-step guide with complete example repositories that you can adapt for your own projects.
+
+The material is designed for researchers, research software engineers, analysts, and postgraduate students in health and operations research who want to build transparent, trustworthy simulation models. Educators and trainers can adopt the book as a complete syllabus for a short course or reuse individual chapters as standalone teaching units (for example, sessions on RAP, testing, packaging, or sharing models),  and should cite the resource when they do so in line with the provided citation below. The accompanying code is released under an MIT licence, and the text is available under a CC BY-SA 4.0 licence, allowing reuse and adaptation with appropriate attribution.
+
+> If you use the DES RAP book in your teaching, research, or training, we'd love to hear about it. Please [get in touch](/pages/guide/further_info/feedback.qmd) to share how you've used the material, suggest improvements, or point us to example models or case studies that others might find helpful.
+
+To get the most from this resource, you should be comfortable with basic programming in either Python or R and have some familiarity with probability and basic statistics. No prior DES experience is required: short introductions to DES, reproducible analytical pipelines, and free and open source software are provided in the "Intros" section and linked below.
+
+An engaged learner can complete the core step-by-step guide in around 10-15 hours, including time to run the code examples and attempt the exercises. You can work through the material in order as a structured course, or dip into specific sections (such as input modelling, verification and validation, or sharing and archiving) as needed.
+
+After working through this resource, you will be able to:
+
+* Set up **version control** and reproducible **environments** for your DES RAP project.
+* Structure your work as a **package**, with clear, reusable code organisation.
+* Manage **inputs** systematically, including data, parameters, and validation.
+* Build a working **DES model** with entities, processes, randomness, and logging.
+* Carry out **output analysis** and **experimentation**, including warm-up, replications, and scenario/sensitivity analysis.
+* Apply **verification, validation, testing, and quality assurance** to increase trust in your model.
+* Improve **style, documentation, and automation** with linting, docstrings, and GitHub Actions.
+* **Collaborate and share** your work effectively, including code review, licensing, citation, changelogs, and archiving.
+
+<br>
 
 ```{=html}
 <div class="value-grid">
@@ -86,19 +107,186 @@ We have dedicated pages explaining the foundations, helpful if you're new to any
 
 <br>
 
-This resource is an output of **STARS**, a research project led by Associate Prof. **Tom Monks** [![ORCID](images/orcid.png)](https://orcid.org/0000-0003-2631-4481).
+This resource is an output of **STARS**, a research project led by Associate Prof. **Tom Monks** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0003-2631-4481).
 
-The book is written by **Amy Heather** [![ORCID](images/orcid.png)](https://orcid.org/0000-0002-6596-3479). It has been reviewed by:
+The book is written by **Amy Heather** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0002-6596-3479). It has been reviewed by:
 
-* Prof. **Nav Mustafee** [![ORCID](images/orcid.png)](https://orcid.org/0000-0002-2204-8924)
-* Dr. **Alison Harper** [![ORCID](images/orcid.png)](https://orcid.org/0000-0001-5274-5037)
-* Associate Prof. **Tom Monks** [![ORCID](images/orcid.png)](https://orcid.org/0000-0003-2631-4481)
-* **Fatemeh Alidoost** [![ORCID](images/orcid.png)](https://orcid.org/0009-0000-0252-560X)
-* Dr. **Rob Challen** [![ORCID](images/orcid.png)](https://orcid.org/0000-0002-5504-7768)
-* **Tom Slater** [![ORCID](images/orcid.png)](https://orcid.org/0009-0007-0838-7499)
+* Prof. **Nav Mustafee** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0002-2204-8924)
+* Dr. **Alison Harper** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0001-5274-5037)
+* Associate Prof. **Tom Monks** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0003-2631-4481)
+* **Fatemeh Alidoost** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0009-0000-0252-560X)
+* Dr. **Rob Challen** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0002-5504-7768)
+* **Tom Slater** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0009-0007-0838-7499)
 
 The STARS project is supported by the Medical Research Council [grant number MR/Z503915/1] from 1st May 2024 to 31st October 2026. The listed researchers are associated with the **University of Exeter** Medical and Business Schools, and the **University of Bristol** School of Engineering, Mathematics and Technology.
 
 You can find out more about our project on the [**STARS project website**](https://pythonhealthdatascience.github.io/stars/){target="_blank"}. If you use this resource, **please cite us:**
 
 > Heather, A., Monks, T., Mustafee, N., Harper, A., Alidoost, F., Challen, R., & Slater, T. (2025). DES RAP Book: Reproducible Discrete-Event Simulation in Python and R. https://github.com/pythonhealthdatascience/des_rap_book. https://doi.org/10.5281/zenodo.17094155.
+
+<br>
+
+<i><b>Keywords:</b> discrete-event simulation; reproducible analytical pipelines; health services research; Python; R; simulation modelling; research software engineering; open-source tools; SimPy; simmer.</i>
+
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "TrainingMaterial",
+  "@id": "https://doi.org/10.5281/zenodo.17094155",
+  "http://purl.org/dc/terms/conformsTo": {
+    "@type": "CreativeWork",
+    "@id": "https://bioschemas.org/profiles/TrainingMaterial/1.0-RELEASE"
+  },
+  "name": "DES RAP Book: Reproducible Discrete-Event Simulation in Python and R",
+  "description": "An open, self-paced training resource that teaches how to design, implement, and share discrete-event simulation (DES) models in Python and R as part of a reproducible analytical pipeline (RAP).",
+  "keywords": [
+    "discrete-event simulation",
+    "reproducible analytical pipelines",
+    "health services research",
+    "Python",
+    "R",
+    "simulation modelling",
+    "research software engineering",
+    "open-source tools",
+    "SimPy",
+    "simmer"
+  ],
+  "url": "https://pythonhealthdatascience.github.io/des_rap_book/",
+  "identifier": [
+    {
+      "@type": "PropertyValue",
+      "propertyID": "DOI",
+      "value": "10.5281/zenodo.17094155"
+    }
+  ],
+  "abstract": "This practical guide shows you how to build reproducible discrete-event simulation models (DES) that fit into a reproducible analytical pipeline (RAP), with tips that benefit all types of models and analysis. The resource combines a step-by-step guide with complete example repositories in Python and R.",
+  "about": [
+    {
+      "@type": "DefinedTerm",
+      "name": "Discrete-event simulation"
+    },
+    {
+      "@type": "DefinedTerm",
+      "name": "Reproducible analytical pipelines"
+    },
+    {
+      "@type": "DefinedTerm",
+      "name": "Health services research"
+    },
+    {
+      "@type": "DefinedTerm",
+      "name": "Research software engineering"
+    }
+  ],
+  "audience": [
+    {
+      "@type": "Audience",
+      "audienceType": "researchers"
+    },
+    {
+      "@type": "Audience",
+      "audienceType": "research software engineers"
+    },
+    {
+      "@type": "Audience",
+      "audienceType": "analysts"
+    },
+    {
+      "@type": "Audience",
+      "audienceType": "postgraduate students in health and operations research"
+    }
+  ],
+  "author": [
+    {
+      "@type": "Person",
+      "name": "Amy Heather",
+      "@id": "https://orcid.org/0000-0002-6596-3479"
+    }
+  ],
+  "contributor": [
+    {
+      "@type": "Person",
+      "name": "Tom Monks",
+      "@id": "https://orcid.org/0000-0003-2631-4481"
+    },
+    {
+      "@type": "Person",
+      "name": "Nav Mustafee",
+      "@id": "https://orcid.org/0000-0002-2204-8924"
+    },
+    {
+      "@type": "Person",
+      "name": "Alison Harper",
+      "@id": "https://orcid.org/0000-0001-5274-5037"
+    },
+    {
+      "@type": "Person",
+      "name": "Fatemeh Alidoost",
+      "@id": "https://orcid.org/0009-0000-0252-560X"
+    },
+    {
+      "@type": "Person",
+      "name": "Rob Challen",
+      "@id": "https://orcid.org/0000-0002-5504-7768"
+    },
+    {
+      "@type": "Person",
+      "name": "Tom Slater",
+      "@id": "https://orcid.org/0009-0007-0838-7499"
+    }
+  ],
+  "competencyRequired": [
+    "Basic programming in Python or R (functions, packages, simple scripts)",
+    "Familiarity with probability and basic statistics"
+  ],
+  "educationalLevel": "intermediate",
+  "inLanguage": "en",
+  "learningResourceType": [
+    "online book",
+    "step-by-step guide",
+    "worked examples"
+  ],
+  "license": [
+    "https://opensource.org/license/mit",
+    "https://creativecommons.org/licenses/by-sa/4.0/"
+  ],
+  "mentions": [
+    {
+      "@type": "SoftwareApplication",
+      "name": "SimPy"
+    },
+    {
+      "@type": "SoftwareApplication",
+      "name": "simmer"
+    },
+    {
+      "@type": "SoftwareApplication",
+      "name": "Git"
+    },
+    {
+      "@type": "SoftwareApplication",
+      "name": "GitHub"
+    }
+  ],
+  "teaches": [
+    "Setting up version control and reproducible environments for DES RAP projects",
+    "Structuring simulation projects as reusable packages",
+    "Managing inputs, parameters, and experiments in a reproducible way",
+    "Building DES models with entities, processes, randomness, and logging",
+    "Performing output analysis, warm-up, replications, and scenario/sensitivity analysis",
+    "Applying verification, validation, testing, and quality assurance to simulation models",
+    "Automating checks with linters and continuous integration",
+    "Documenting, licensing, citing, and archiving DES models for reuse"
+  ],
+  "timeRequired": "PT10H",
+  "provider": {
+    "@type": "Organization",
+    "name": "STARS project, University of Exeter and University of Bristol"
+  },
+  "datePublished": "2025-09-10",
+  "creativeWorkStatus": "Active",
+  "version": "1.0"
+}
+</script>
+
+<!-- datePublished is set to date of first release -->