python-intermediate-development Add alt-text to all images and consider captioning

Add alt-text to all images and consider captioning some of them. The caption is now in the place where the alt-text used to be, and the alt-text is in an extra attribute after the definition of the image (e.g. caption text{alt='Alt text'})

Jun 24 '25 09:06 steve-crouch

From some quick greping on the Markdown source in episodes it looks like all the current figures have alt text attributes set unless I'm misintrepreting (or this is intended to apply to files outside of episodes!):

Output of grep -E -r '\!\[.*\]\(.+\)' episodes

episodes/50-section5-intro.md:![](fig/section5-overview.svg){alt='Managing software' .image-with-shadow width="1000px" }
episodes/14-collaboration-using-git.md:![Software development lifecycle with Git](fig/git-lifecycle.svg){alt='Development lifecycle with Git, containing Git commands add, commit, push, fetch, restore, merge and pull' .image-with-shadow width="600px"}
episodes/14-collaboration-using-git.md:![](fig/git-distributed.png){alt='git-distributed' .image-with-shadow width="400px"}
episodes/14-collaboration-using-git.md:![](fig/git-feature-branch.svg){alt='Git feature branch workflow diagram' .image-with-shadow width="800px"}
episodes/14-collaboration-using-git.md:![](fig/github-main-branch.png){alt="Software project's main branch" .image-with-shadow width="600px"}
episodes/14-collaboration-using-git.md:![](fig/github-develop-branch.png){alt="Software project's develop branch" .image-with-shadow width="600px"}
episodes/41-code-review.md:![](fig/code-review-sequence-diagram.svg){alt='Code review process sequence' .image-with-shadow width="600px"}
episodes/41-code-review.md:  ![](fig/github-pull-request-tab.png){alt='GitHub pull requests tab' .image-with-shadow width="900px"}
episodes/41-code-review.md:  ![](fig/github-create-pull-request.png){alt='Creating a new pull request.' .image-with-shadow width="900px"}
episodes/41-code-review.md:  ![](fig/github-submit-pull-request.png){alt='Submitting a pull request.' .image-with-shadow width="900px"}
episodes/41-code-review.md:  ![](fig/github-add-collaborator.png){alt='Adding a collaborator in GitHub' .image-with-shadow width="900px"}
episodes/41-code-review.md:  ![](fig/github-pull-request-files-changed.png){alt='The files changed tab of a pull request' .image-with-shadow width="900px"}
episodes/41-code-review.md:  ![](fig/github-pull-request-add-comment.png){alt='Adding a review comment to a pull request' .image-with-shadow width="800px"}
episodes/41-code-review.md:  ![](fig/github-pull-request-add-suggestion.png){alt='Adding a suggestion to a pull request' .image-with-shadow width="800px"}
episodes/41-code-review.md:  ![](fig/github-submit-pull-request-review.png){alt='Using the finishing your review dialog' .image-with-shadow width="800px"}
episodes/41-code-review.md:  ![](fig/github-finish-pull-request-review.png){alt='Using the finishing your review dialog' .image-with-shadow width="900px"}
episodes/41-code-review.md:  ![](fig/github-respond-to-review-comment-with-emoji.png){alt='Responding to a review comment with an emoji' .image-with-shadow width="800px"}
episodes/41-code-review.md:  ![](fig/github-respond-to-review-comment-with-commit-link.png){alt='Responding to a review comment with a link to commit' .image-with-shadow width="800px"}
episodes/41-code-review.md:  ![](fig/github-merge-pull-request.png){alt='Merging a pull request in GitHub' .image-with-shadow width="800px"}
episodes/12-virtual-environments.md:![Python Environment Hell from [XKCD](https://xkcd.com/1987/) (Creative Commons Attribution-NonCommercial 2.5 License)](fig/python-environment-hell.png){alt='Python environment hell XKCD comic'}
episodes/32-software-architecture-design.md:![](fig/xkcd-good-code-comic.png){alt='Writing good code comic' .image-with-shadow width="400px" }
episodes/32-software-architecture-design.md:![](fig/example-architecture-diagram.svg){alt='Diagram showing proposed architecture of the problem' width="600px" }
episodes/00-setting-the-scene.md:![Course overview diagram](fig/course-overview.svg){alt="Course overview diagram. Arrows connect the following boxed text in order: 1) Setting up software environment 2) Verifying software correctness 3) Software development as a process 4) Collaborative development for reuse 5) Managing software over its lifetime."}
episodes/23-continuous-integration-automated-testing.md:![](fig/ci-initial-ga-build.png){alt='Continuous Integration with GitHub Actions - Initial Build' .image-with-shadow width="1000px"}
episodes/23-continuous-integration-automated-testing.md:![](fig/ci-initial-ga-build-log.png){alt='Continuous Integration with GitHub Actions - Build Log' .image-with-shadow width="1000px"}
episodes/23-continuous-integration-automated-testing.md:![](fig/ci-initial-ga-build-details.png){alt='Continuous Integration with GitHub Actions - Build Details' .image-with-shadow width="1000px"}
episodes/23-continuous-integration-automated-testing.md:![](fig/ci-ga-build-matrix.png){alt='Continuous Integration with GitHub Actions - Build Matrix' .image-with-shadow width="1000px"}
episodes/20-section2-intro.md:![Section 2 Overview](fig/section2-overview.svg){alt='Tools for scaled software testing'}
episodes/13-ides.md:![](fig/pycharm-open-project.png){alt='View of an opened project in PyCharm' .image-with-shadow width="1000px" }
episodes/13-ides.md:![](fig/pycharm-missing-python-interpreter.png){alt='Missing Python Interpreter Warning in PyCharm' .image-with-shadow width="800px" }
episodes/13-ides.md:  ![](fig/pycharm-configuring-interpreter.png){alt='Configuring Python Interpreter in PyCharm' .image-with-shadow width="800px"}
episodes/13-ides.md:![](fig/pycharm-installed-packages.png){alt='Packages Currently Installed in a Virtual Environment in PyCharm' .image-with-shadow width="800px"}
episodes/13-ides.md:  ![](fig/pycharm-add-library.png){alt='Installing a package in PyCharm' .image-with-shadow width="800px" }
episodes/13-ides.md:  ![](fig/pycharm-add-run-configuration.png){alt='Adding a Run Configuration in PyCharm' .image-with-shadow width="800px" }
episodes/13-ides.md:  ![](fig/pycharm-run-configuration-popup.png){alt='Run Configuration Popup in PyCharm' .image-with-shadow width="800px" }
episodes/13-ides.md:![](fig/pycharm-syntax-highlighting.png){alt='Syntax Highlighting Functionality in PyCharm' .image-with-shadow width="1000px" }
episodes/13-ides.md:![](fig/pycharm-code-completion.png){alt='Code Completion Functionality in PyCharm' .image-with-shadow width="600px" }
episodes/13-ides.md:![](fig/pycharm-code-reference.png){alt='Code References Functionality in PyCharm' .image-with-shadow width="1000px" }
episodes/13-ides.md:   ![](fig/pycharm-code-search.png){alt='Code Search Functionality in PyCharm' .image-with-shadow width="800px" }
episodes/13-ides.md:   ![](fig/pycharm-find-panel.png){alt='Code Search Functionality in PyCharm' .image-with-shadow width="1000px" }
episodes/13-ides.md:![](fig/pycharm-version-control.png){alt='Version Control Functionality in PyCharm' .image-with-shadow width="1000px" }
episodes/13-ides.md:![](fig/pycharm-run-script.png){alt='Running a script from PyCharm' .image-with-shadow width="800px" }
episodes/53-improvement-through-feedback.md:![](fig/github-milestones.png){alt='Milestones in GitHub' .image-with-shadow width="1000px"}
episodes/53-improvement-through-feedback.md:![](fig/github-create-milestone.png){alt='Create a milestone in GitHub' .image-with-shadow width="1000px"}
episodes/53-improvement-through-feedback.md:![](fig/github-new-milestone-description.png){alt='Create a milestone in GitHub' .image-with-shadow width="800px"}
episodes/53-improvement-through-feedback.md:![](fig/github-assign-milestone.png){alt='Milestones in GitHub' .image-with-shadow width="1000px"}
episodes/53-improvement-through-feedback.md:![](fig/github-milestone-in-project-board.png){alt='Milestones in Project Boards' .image-with-shadow width="900px"}
episodes/15-coding-conventions.md:![](fig/pycharm-indentation.png){alt='Python code indentation settings in PyCharm' .image-with-shadow width="800px"}
episodes/15-coding-conventions.md:![](fig/pycharm-whitespace.png){alt='Python code whitespace settings in PyCharm' .image-with-shadow width="800px"}
episodes/10-section1-intro.md:![Section 1 Overview](fig/section1-overview.svg){alt='Tools needed to collaborate on code development effectively'}
episodes/60-wrap-up.md:![](fig/wrapup-perceived-usefulness-time.png){alt='Usefulness versus time to master grid' .image-with-shadow width="800px"}
episodes/60-wrap-up.md:![](fig/wrapup-concept-map.png){alt='Overview of tools and techniques covered in the course' .image-with-shadow width="800px"}
episodes/60-wrap-up.md:![](fig/wrapup-concept-map-difficulty-level.png){alt='Overview of topics covered in the course based on level of difficulty' .image-with-shadow width="800px"}
episodes/11-software-project.md:![](fig/inflammation-study-pipeline.png){alt='Snapshot of the inflammation dataset' .image-with-shadow width="800px" }
episodes/11-software-project.md:  ![](fig/github-fork-repository.png){alt='Software project fork repository in GitHub' .image-with-shadow width="900px" }
episodes/11-software-project.md:  ![](fig/github-fork-repository-confirm.png){alt='Making a fork of the software project repository in GitHub' .image-with-shadow width="600px" }
episodes/11-software-project.md:  ![](fig/github-forked-repository-own.png){alt='View of your own fork of the software repository in GitHub' .image-with-shadow width="900px" }
episodes/11-software-project.md:![](fig/clone-repository.png){alt='URL to clone the repository in GitHub' .image-with-shadow width="800px" }
episodes/40-section4-intro.md:![](fig/section4-overview.svg){alt='Software design and architecture' .image-with-shadow width="1000px" }
episodes/51-managing-software.md:![](fig/github-issue-list.png){alt='List of project issues in GitHub' .image-with-shadow width="1000px"}
episodes/51-managing-software.md:![](fig/github-new-issue.png){alt='Creating a new issue in GitHub' .image-with-shadow width="1000px"}
episodes/51-managing-software.md:![](fig/github-reference-comments-commits.png){alt='Referencing comments and commits in GitHub' .image-with-shadow width="700px"}
episodes/51-managing-software.md:  ![](fig/github-new-project.png){alt='Adding a new project board in GitHub' .image-with-shadow width="800px"}
episodes/51-managing-software.md:    ![](fig/github-project-template.png){alt='Selecting a project board template in GitHub' .image-with-shadow width="800px"}
episodes/51-managing-software.md:  ![](fig/github-project-settings.png){alt='Project board setting in GitHub' .image-with-shadow width="800px"}
episodes/51-managing-software.md:  ![](fig/github-project-description.png){alt='Adding project description and metadata in GitHub' .image-with-shadow width="800px"}
episodes/51-managing-software.md:  ![](fig/github-project-view-add-remove-items.png){alt='Default card board in GitHub' .image-with-shadow width="800px"}
episodes/51-managing-software.md:  ![](fig/github-project-new-items.png){alt='Adding issues and notes to a project board in GitHub' .image-with-shadow width="800px"}
episodes/51-managing-software.md:  ![](fig/github-convert-task-to-issue.png){alt='Converting a task to issue' .image-with-shadow width="800px"}
episodes/51-managing-software.md:  ![](fig/github-project-add-view.png){alt='Add another project view' .image-with-shadow width="800px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/numpy-incompatible-shapes.png){alt='NumPy arrays of incompatible shapes' .image-with-shadow width="800px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/numpy-shapes-after-new-axis.png){alt="NumPy arrays' shapes after adding a new\_axis" .image-with-shadow width="800px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/numpy-shapes-after-broadcasting.png){alt="NumPy arrays' shapes after broadcasting" .image-with-shadow width="800px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/pycharm-test-framework.png){alt='Setting up test framework in PyCharm' .image-with-shadow width="1000px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/pytest-pycharm-run-tests.png){alt='Running pytest in PyCharm' .image-with-shadow width="1000px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/pytest-pycharm-check-config.png){alt='Ensuring testing configurations in PyCharm are correct' .image-with-shadow width="800px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/pytest-pycharm-run-single-test.png){alt='Running a single test in PyCharm' .image-with-shadow width="800px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/pytest-pycharm-set-breakpoint.png){alt='Setting a breakpoint in PyCharm' .image-with-shadow width="600px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/pytest-pycharm-debug.png){alt='Debugging in PyCharm' .image-with-shadow width="1000px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/pytest-pycharm-console.png){alt='Debugging in PyCharm' .image-with-shadow width="1000px"}
episodes/24-diagnosing-issues-improving-robustness.md:![](fig/pytest-pycharm-all-tests-pass.png){alt='All tests in PyCharm are successful' .image-with-shadow width="1000px"}
episodes/30-section3-intro.md:![](fig/section3-overview.svg){alt='Software design and architecture overview flowchart'}
episodes/42-software-reuse.md:![Continuous Integration build in GitHub Actions](https://github.com/<your_github_username>/python-intermediate-inflammation/actions/workflows/main.yml/badge.svg?branch=main)

(the instance in 42-software-reuse.md which appears not to have an alt-text set is actually embedded in a Markdown snippet as an example of creating a status badge so I assume not having an alt text here is intentional / correct)

Some of the existing alt-texts could possibly be expanded to be more descriptive, but I'm not sure if that is in scope for this issue @steve-crouch?

For the captions, do we want these for all figures? And in terms of differences between the caption and alt-text for a given image - my understanding would be the alt-text should describe the visual content of the image (to improve accessibility) while the caption is more about adding additional context / explanation about what is shown (without needing to recreate what is shown in the image) - does this sound reasonable?

Jun 24 '25 15:06 matt-graham

I discussed this issue with @douglowe in the maintainers meeting on 2025-08-26 and showed an example of form of changes I was proposing for Collaboration with Git episode in 73f53de20a30028ea80a1c5c87742763a08eef1c - in summary making the alt-text a self-contained description of figure content. @douglowe agreed this seemed a good thing to do and suggested breaking down this issue with sub-issues for updating alt-texts on a per-episode basis to keep associated pull-requests smaller / more easily reviewed and also allow distributing the work.

Aug 26 '25 10:08 matt-graham