Skip to content

Contributing

Maintainer material

This section is for people editing the course, not for students learning from it. Students do not need anything here. If you only want to learn project management, go to Start Here.

This page explains how to propose a change to the course. It is the short version; the repository's CONTRIBUTING.md has the full process.

Who contributes

Contributor Typical contribution
Students Typos, unclear explanations, broken links, "this answer seems wrong"
Teaching assistants Lab improvements, extra worked examples, quiz questions
Instructors New lessons, case studies, course mapping, assessment design
Maintainers Structure, tooling, deployment, review

Students and TAs: do not be put off by the tooling. A correction to one sentence is a genuinely valuable contribution, and you do not need to understand the build to make one. The only thing you must respect is the accuracy rule below.

The one hard rule: accuracy

This course makes a commitment that shapes every edit:

No fabricated references, standards, statistics, or citations.

In practice:

  • Do not add a statistic, quotation, or citation you cannot verify against a real source.
  • Cite real sources by their canonical title and publisher — the list in Standards & Further Reading shows the format.
  • Where a real figure would normally be quoted, either omit it or describe the finding qualitatively. "Estimates are frequently optimistic" is fine; an invented percentage is not.
  • Label any synthetic or illustrative scenario as illustrative. The case study template has the required wording.
  • Keep technical statements about tools, standards, and methods correct as of the date of writing.

A change that breaks this rule will not be merged, however good it otherwise is.

Ways to contribute

The easiest and most useful contribution. Fix a typo, clarify a sentence, repair a link, or propose a better model answer. One file, one change.

Author a lesson, lab, case study, or quiz. Start from the matching template in Templates and follow the module anatomy in ARCHITECTURE.md.

Navigation, accessibility, layout, or the build itself. Read Local Development first, and keep the site lightweight — this is a static documentation site, not an application.

Where things live

Path What it is
docs/course-content/ The 13 teaching modules
docs/labs/, docs/case-studies/ Practical work and analysis
docs/templates/ Artefact and authoring templates
docs/self-assessment/ Quizzes, with answers hidden
docs/reference/ Glossary and curated sources
docs/instructor/ Instructor-only material
docs/contributing/ This section
mkdocs.yml Navigation lives here. A page not listed here triggers a build warning
tools/ Local validators
.github/workflows/ Continuous integration and publishing

Project documentation for maintainers sits at the repository root: ARCHITECTURE.md, IMPLEMENTATION-PLAN.md, NAMING-CONVENTIONS.md, and CONTRIBUTING.md.

Workflow in brief

  1. Create a branch: fix/schedule-typo, content/risk-lessons, docs/glossary-additions.
  2. Make the change.
  3. If you added or renamed a page, add it to nav in mkdocs.yml.
  4. Run the checks: python tools/validate-structure.py.
  5. Open a pull request explaining what changed and why.

Run the full check suite before opening a pull request:

python tools/validate-structure.py     # structure, naming, internal links
python tools/check-curriculum.py       # 32-session curriculum integrity
mkdocs build --strict                  # authoritative build

See Local Development for how to run these, and Deployment for how a merged change reaches the website.

Style

  • Follow the naming rules in NAMING-CONVENTIONS.md.
  • Write student-facing content in the second person ("you will build…").
  • One idea per page. Link to the canonical page instead of duplicating it.
  • Prefer a Mermaid diagram over an image — diagrams stay readable in the repository and in a diff.
  • Use the standard "At a glance" header on every lesson, lab, case study, and assessment.