Updating the Lesson Template

This post originally appeared on the Software Carpentry website.

A couple of weeks ago, we asked our lesson maintainers what changes they would like to see in our lesson template based on their experiences getting Version 5.3 ready for publication. Their comments are summarized below; it's an ambitious list, but I think we can do most or all of this between now and September. If there are other things you think we should change in the way we structure lessons (rather than in particular lessons themselves), please add comments, and if you'd like to dive into one of these, please checkout the current lesson-template issues and create a pull request against the lesson-template repository.

1. Remove the Legend section: nobody's sure what to do with it, and the warmup for the running example in each lesson goes better in index.md.

2. Allow level-2 sub-headings within topic files (but discourage their use, since anything long enough to need sub-headings should be broken into smaller pieces).

3. Add a callout-style for "common mistakes" or "warnings" (similar to those used in O'Reilly books and elsewhere)

4. Add next/previous links between topics and other files.

5. Generate a single-page PDF of the whole lesson.

6. Add translation guidelines and support.

7. Add a page showing what all available styles look like.

8. Add more pointers to the FAQ so that lesson maintainers know where to accumulate wisdom.

9. Use Inconsolata instead of Courier New for code.

10. Add something to code blocks to say what language they're in. (We use styles to control rendering, but nothing appears in the final HTML to say, "Hey, I'm a Bash script...")

11. Add more checks for broken links to validator (do these on the generated HTML, not the Markdown).

12. Validator should show snippets and line numbers to give context for errors.

13. Add make update to update from template, and have it produce a change log.

14. Add a "how to cite me" section to each lesson's index.md and a CITATION file to each lesson's repo.

15. Add the current maintainers' contact info to the CONTRIBUTING.md.

16. Add a section to CONTRIBUTING.md summarizing discussion to date of what not to change in the lesson (so that old arguments aren't rehashed).

17. Move the motivation slides to the slideshows repo, but keep the content (in prose form) at the start of instructors.md to show new instructors how to motivate a lesson.

18. Have a tool to generate a single-page deck.js slideshow with one image per slide so that instructors can easily show them off when live coding.

19. Add a link to a "how to get started on your own" section (like Daniel Chen's post) on the main Software Carpentry website (probably the lessons page).

20. Add solutions to all challenges.

21. Add documentation to lesson-example explaining how to create a downloadable ZIP of data files required for a particular lesson and where to archive it (so that we all do it in the same way).

22. Add links to each lesson's reference guide to the main web site (again, probably the lessons page), and make sure those print nicely.