User Tools

Site Tools


Course Materials Development Process

The purpose of this document is to propose a standardized workflow for the development of our teaching materials, with an ultimate goal of providing a better teaching and learning experience both to our students and to our instructors. This document is predicated on a number of existing documents as well as documents that need to be developed. For example, we have some course outlines at that are a good start towards a solid course structure, but many of the outlines lack measurable goals for the workshops. We’ll produce a better learning experience for our students if we can specify up front what we expect students to be able to do at the end of the course. You might like to look at for some pointers.

I’ll be working on those outlines and using the revised goals as input into the following process.

When reading this please don’t get locked into thinking things like “but git doesn’t work like that so this process won’t work.” We need to get the process right and then decide on the implementation. Our tools shouldn’t dictate our workflow.

The following diagram describes the proposed workflow.

Trainers retrieve material from the Production archive to use for a course. This material is available in both editable (e.g., odp, pptx, txt, md) and fixed formats (e.g., pdf). Trainers should modify copies locally if they want/need to make changes for their workshop. Those changes, if proposed as a permanent change, should then be committed only to the Development archive. If they don’t want to propose changes then they do nothing. Any material submitted to the Development archive for addition to the Production archive will then initiate a Gatekeeper process. The Gatekeeper process (to be described in more detail later) decides if the proposed change meets the relevant criteria and if it does, then the change is committed. Rinse and repeat.

The goal of this process is to make sure that material in the Production archive is always ‘fit for purpose’ and has been tested against a number of criteria before it’s committed.

Gatekeeper Process

Currently our gatekeeper process can at best be described as a passive one. Someone makes a change to course material and commits that change to the Git archive. Unless there is some sort of major outcry, that material becomes part of the current production archive. There may be a process of additional refinement on the material but it’s rare for the change to be reversed.

This can happen at any time. A trainer preparing for a workshop may suddenly find that the material they planned to use has changed dramatically since they used it on a previous occasion perhaps even few weeks before. Trainers may also share their own personalized copies, working around whatever is in the production system and leaving the organization with multiple, possibly conflicting or out of date copies in the repository (?)

In order to avoid those problems, which have impacted several members of the NSRC team when delivering classes, the gatekeeper process needs to become more structured. If a trainer wishes to make changes then he or she should commit them to the development archive for assessment.

I’m proposing that for each subject area that we teach, for example, Campus Network Design (CND), Network Monitoring and Management (NMM), DNS, Security (SEC) we have a group of three responsible for managing the process. Each group would consist of the Master of Curriculum (MC - currently asjl), a Subject Matter Expert (SME) and another trainer who isn’t deeply involved in the topic.

I know many people reading this as convinced that they’re experts on everything :-) and need to be across all that we do, but the role of this group is to check that the proposed change meets a number of criteria listed below. (This list is not exhaustive - I expect discussion here)

Acceptance Criteria

Proposed changes MUST answer at least one of these questions:

  • Do they meet the teaching goals of the workshop?
  • Do they improve/change the teaching goals?
  • Do they remove things from the teaching goals?
  • Do they fix bugs/problems?
  • Have proposed changes been tested against measurable goals?
  • Do the changes allow the course to be taught in a realistic time?

The person proposing the changes will need to submit a form, document, or some kind of information that explains what has changed and how these questions apply to the changes.


  • Does the material conform to House Styles?
  • Format dependent e.g. standard template for presentations, markdown files rendered as .pdf using pandoc
  • Has the material been checked for grammar, spelling by the committer?
  • Does it meet the naming convention for files? (obviously we need a spec for this. brian, phil and hervey have discussed this in the last year and might have a scheme that just needs to be documented)
  • Which course is this material for?
  • Some courses can be general material for any course e.g. Unix Intro Exercises/Labs
  • If there is an explicit goal in the course outline e.g. “At the end of the course, you will be able to do XYZ”, then does this exercise get them to the point where they can “do XYZ”?
  • Does the exercise work with the virtual environment?
  • Are there instructor notes?

The Course Gatekeeper Group will assess the changes and see that they meet the criteria and once the material has done that then they will inform that proposed change is agreed unless there is substantive disagreement within a short time period. This process can be kept lightweight and relatively unobtrusive. If we are getting the process right then the small changes for fixing typos and other minor mistakes should not be needed.

Development archive

This archive looks like our current archive and work will need to be done to material in here to get it through the Gatekeeper process.

Material in this archive:

Ready for deployment but awaiting approval May be under active development Archives of previously used material

This material SHOULD NOT be used in courses unless they are prototypes that are undergoing active development. The goal should be to get material into the Production archive as soon as possible.

Production archive

Material in this archive:

meets the specifications for presentations, labs added via the Gatekeeper process is available on a read-only basis is provided in an editable format

We need to define who can read from this archive:

trainers others?

What’s the appropriate tool for this?

git archive with restricted write access to gatekeepers only? material is attached to a course via tags instead of separate silos (as at present) Workshop

Trainers still retain the option of organising the material as they see fit but don’t have the ability to push changes without getting agreement from the wider group.

General note: It’s unclear from this whether our process needs to account for minor changes like critical bugs that need to be rolled out ASAP, and larger structural changes that might aggregate a lot of commits before they are ready to be released to the production archive. I need to do some more thinking, but I think we either need two flows or a process that handles both cases gracefully. Atomic commits make me nervous unless they are for something like a critical bugfix.

2015/repo-documentation/course-materials-dev-process.txt · Last modified: 2016/02/03 05:04 (external edit)