Retiring this handbook

[tobyhodges]

Now that we have a Lesson Development Training curriculum (in alpha), and the new lesson infrastructure has been rolled out, I’m making plans to retire the Curriculum Development Handbook. If you have any concerns about this, or if you’d like to help me take care of it, please respond here.

Chapter-by-chapter plan

(Context for the below: the “Lesson Developer Handbook” is a new resource/collection of resources that will be added to docs.carpentries.org at the same time as the CDH content is removed/relocated.)

1. Guiding Principles - so far not replicated elsewhere Toby’s plan: put this into Lesson Developer Handbook and link to CLDT for those who want more detail/guidance
2. Our curriculum structure Toby’s plan: put the summary table from this chapter into Lesson Developer Handbook, accompanied by definitions for the key terms
3. Deciding what to teach - this content is covered in more detail in CLDT Toby’s plan: remove this - it is summarised in Guiding Principles (above, can add link(s) to relevant CLDT content) and the lesson development training curriculum (and resources referenced therein) provides more detail for those who want it.
4. Designing challenges Toby’s plan: remove this and link to relevant episodes of CLDT, sections of Teaching Tech Together, from Lesson Developer Handbook
5. Developing content Toby’s plan: remove this. It is covered in more detail in the lesson development training curriculum
6. Community development roles - some of this is replicated in docs.carpentries.org and carpentries.org, some info is outdated Toby’s plan: move this info into the relevant parts of docs.carpentries.org/the Lesson Developer Handbook - and update it
7. The lesson life cycle - introduced in lesson development training, but that section links to the CDH for more detail Toby’s plan: move this content to Lesson Developer Handbook, link to its new location there from training curriculum
8. Technological introductions - this refers extensively to the old lesson infrastructure and is largely obsolete now. Toby’s plan: remove this
9. Appendix A. The Carpentries Incubator - some of this is duplicated e.g. on carpentries-incubator.org Toby’s plan: move this content to the Lesson Developer Handbook
10. Appendix B. Bibliography - empty
11. Appendix C. Adapting existing lessons for The Carpentries - most of this is obsolete/needs to be rewritten for Workbench Toby’s plan: add a similar resource as a HOWTO guide to the Workbench documentation.
12. Appendix D. Lesson Sprint Recommendations Toby’s plan: move this content to the Lesson Developer Handbook

Where should lesson developers look for info after this?

After I have completed this process, lesson developers will be able to refer to the following resources for guidance: Collaborative Lesson Development Training curriculum - for a guidance through the process of designing and developing a lesson The Lesson Developer Handbook (will be part of docs.carpentries.org, exact link coming soon) - for reference during the lesson development process The lesson infrastructure documentation - for help getting started with and using The Carpentries Workbench infrastructure for building a lesson website.

[tobyhodges]

[Adding some context shared in a Slack thread, for anyone who might be reading here and is curious.]

Some overlap between resources is inevitable, but my main motivation for retiring the CDH is that it is a combination of content that fits into too many of those different quadrants described by diataxis.fr and as such is not as useful as it could be for any of its intended audiences. The aim is to relocate its content to three different resources that better suit people in (at least) three different “modes”:

• Collaborative Lesson Development Training curriculum: for people taking first steps with designing a new lesson
• The Lesson Developer Handbook: a reference on non-infrastructure things for people who have completed those first steps and are working through the longer process of developing, testing, and completing* a lesson (* if a lesson can ever be considered “complete”)
• Workbench documentation: as technical documentation, this will inevitably be a combination of all four of the Diataxis quadrants. This means tutorial content for people taking first steps with using the infrastructure/setting it up on their local system, but also handbook-style reference content for people who are already setup and only want to find out how to do something new e.g. the syntax to add a new figure to an existing episode. Non-exhaustive example for each of the four Diataxis quadrants:
  • a tutorial for people getting started with using the infrastructure to build a lesson
  • how-to guides to answer specific questions people might have e.g. “How do I insert a new episode into the middle of an existing lesson?”
  • reference content providing a detailed description of the {sandpaper} API
  • explanation describing the rationale for the two-step deployment model (this is currently in the Lesson Deployment episode of sandpaper-docs)

As well as being out-of-date, the CDH tries to provide a little bit of all of these. I would prefer to have three separate and more comprehensive resources.

[annajiat]

In absence of a proper substitution(s) for CDH, documentation seems to be missing for jargons as discussed in https://github.com/carpentries/instructor-training/issues/1655