Updating the Lesson Template
Remove the
Legend
section: nobody's sure what to do with it, and the warmup for the running example in each lesson goes better inindex.md
.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).
Add a callout-style for "common mistakes" or "warnings" (similar to those used in O'Reilly books and elsewhere)
Add next/previous links between topics and other files.
Generate a single-page PDF of the whole lesson.
Add translation guidelines and support.
Add a page showing what all available styles look like.
Add more pointers to the FAQ so that lesson maintainers know where to accumulate wisdom.
Use Inconsolata instead of Courier New for code.
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...")
Add more checks for broken links to validator (do these on the generated HTML, not the Markdown).
Validator should show snippets and line numbers to give context for errors.
Add
make update
to update from template, and have it produce a change log.Add a "how to cite me" section to each lesson's
index.md
and a CITATION file to each lesson's repo.Add the current maintainers' contact info to the CONTRIBUTING.md.
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).
Move the motivation slides to the
slideshows
repo, but keep the content (in prose form) at the start ofinstructors.md
to show new instructors how to motivate a lesson.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.
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).
Add solutions to all challenges.
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).Add links to each lesson's reference guide to the main web site (again, probably the lessons page), and make sure those print nicely.