Yet Another Template for Lessons

This post originally appeared on the Software Carpentry website.

After the splitting the repository post, Gabriel Devenyi and Greg Wilson wrote some suggestions for how the new lessons repositories should look like (see Gabriel's post about metadata and Greg's post about overall file structure). From my experience at the Mozilla Science Lab sprint I don't like Gabriel's preq metadata because I don't believe it helps very much. I also don't like Greg's proposal to duplicate some files in every Git repository, so here are some changes that I suggest.

Design Choices

In addition to Greg's design choices:

• Avoid the duplication of files across Git repositories. In Greg's proposal the Git repositories should store CSS and Javascript files needed to properly render the page. We could avoid it.
• Only automate the actions that users and developers will need to do very often. We try to automate workshops' home page but we are going to revert it. For that reason I think we should wait until people complain about the lack of some script before we write it.

Git Repositories

The lesson repositories must have two branches: master and gh-pages. The master branch will store the lessons in Markdown (or any other format, that can be convert to HTML, wanted by the community). The gh-pages branch will store the HTML version of the lesson so that students can view it online.

We had exactly this approach until a few weeks ago in bc repo. Why go back? In bc, we only merge master into gh-pages a few times and I would like to suggest that the topic manintainers do it before the in-service days proposed at last month meeting.

Also, this approach will avoid the problem of have Markdown and HTML side-by-side since Markdown extensions support by Pandoc aren't supported by Jekyll.

Overall Layout for the Master Branch

Changes to Greg's layout:

• Drop glossary.md in favor of linking words to Wikipedia articles.
• Drop web/ to avoid duplication of files across repositories. Web resources, such as CSS files, icons, and Javascript, can be provided by a "third-party" server.
• Drop _layouts/ and _includes to avoid duplication of files across repositories. Makefile will download the needed files from a "third-party" server when needed.
• Drop bin/ to avoid duplication of files across repositories and scripts that no one will use. In case we need some tool for managing lessons it should live in its own repository and we should ask contributors to install it.

Software and Data

I suggest dropping code/index.md and data/index.md to avoid the work of keep them updated. Contributors can find the "description" of the files inside code/ and data/ using:

$ grep 'filename.ext' *.md

Overall Makefile

Changes to Greg's proposal:

• Drop make topic dd-slug because is easy to copy one of the previous topics and correct the filenames if needed.
• make check should run swc-lesson-check (that needs to be installed).
• make site should download the necessary files (e.g. _layouts and _includes) and after that build the lesson website locally for previewing.
• Drop make summary.
• make release should update gh-pages based on master. This should be only used by topic maintainers.