Experiences Adding a Lesson on Make

This post originally appeared on the Software Carpentry website.

In June I added a lesson on Automation and Make. In this blog post, I describe how the lesson evolved, my experiences in porting it into the Software Carpentry lesson template, and the community's response...

In October 2012, my Software Sustainabilility Institute colleague, Steve Crouch wrote an Automation and Make lesson for a Software Carpentry workshop for the University of Oxford. Steve's lesson used Make to run shell commands to process plain-text Protein Data Bank files.

In 2014, the UK's National Computing Service ARCHER started to offer Software Carpentry as part of its training service. As an instructor on these workshops, I thought Make would be a useful lesson to offer, given that Make is still widely used to build C and Fortran-based codes for high-performance computing. At the suggestion of my colleague, Mario Antonioletti, I updated the lesson with a generic word frequency counting example for a workshop at Cranfield University in July. I changed the example to use a Python-based computational fluid dynamics example at Imperial College London in September, but comments from students suggested that understanding the example got in the way of understanding Make (not a good thing!). I reverted to word frequency counting for a workshop at the University of Edinburgh in December.

I'd begun to feel that the lesson should be migrated into Software Carpentry's lesson template, partly to contribute to the community, partly through guilt that here was a lesson being given as part of Software Carpentry that wasn't "official". However, it seemed that the lesson, and workshop, template were constantly evolving. It was difficult to keep up with changes being proposed, and made, across Git repositories, issue trackers, and the mailing list.

With the proposal of a new lesson template last October, and Mario giving the Make lesson, unchanged, at Imperial College London in April, I decided, in June, to bite the bullet. I migrated the Automation and Make lesson into the lesson template, with the help of the lesson example.

And, it went suprisingly smoothly! The lesson was already in MarkDown (my fave mark-up format) so porting into the lesson template was straightforward. The requirement for each page to have a defined set of Learning Objectives forced me look at the content in a new light, to determine exactly what concepts each page should introduce, and reorder or relocate content appropriately. I also had to ensure that these concepts were clearly specified in the Learning Objectives, and that these were summarised in both the reference and glossary. Care also be taken to work through the lesson, multiple times, to ensure that the lesson accurately depicts the responses a student will see at the command-line, and that any sample files or solutions are consistent with the text.

The lesson was added to the Software Carpentry project and web site by Greg Wilson, who then announced it on the mailing list and blog.

What then happened was most interesting, and rewarding. Members of the Software Carpentry community begain raising issues (7 to date) and submitting pull requests (16 to date). Typos that I'd missed (despite, or perhaps because of, numerous updates) were spotted and fixed, clearer ways of explaining concepts were proposed, new challenges were added, new concepts were introduced and updates to confirm to the evolving lesson template were contributed. Thanks to the Software Carpentry community, the lesson has evolved and improved greatly in just over a month. The lesson was also run as part of a workshop run by Damien Irving at the University of Queensland in mid-July (which it might not have been had it remained languishing as a set of MarkDown pages in directories in ARCHER workshop repositories).

In conclusion, if you have a tutorial you already teach students (whether as part of Software Carpentry or other teaching) and it contributes to Software Carpentry's goals of helping researchers do more in less time and with less difficulty, then convert it into a Software Carpentry lesson. It is less intimidating than it might seem. Your lesson will help the community, and the community will help your lesson!