This project is an ongoing effort to develop handouts for Protohaven classes.
These handouts are not meant to be comprehensive guides to using all parts of a tool or process. Instead, they are meant to supplement and reinforce the content covered in the class, so that the student can study the class content on their own time: provide the student with a good baseline of knowledge, go over details that the student may have missed in the moment, reinforce concepts, refer to specific steps, etc.
These handouts are not meant to be clearance checklists.
While working up comments on these drafts, there are three things I'd like us to think about:
In each of these cases, I am interested to know about:
Important feedback that we need for each of these documents:
Do they succeed as a student reference?
Is there appropriate information in this document (not too much, but nothing critical is missing) to support studetns after the class is over:
There is space in these documents (Under “Learning Objectives” for a quick summary of the class activities and goals so that students can re-orient themselves to their experience when looking at the class notes later.
This is going to be largely instructor dependent.
I want to keep track of how people are approaching the workflow of commenting on these drafts, in case we can make things easier.
I (Paul) am happy to take comments on the documents in the following forms:
The upshot: if there are ways that we can make the feedback loop more palatable, I want to try them.
Workflow question: would turning on Section Numbering (“4.5.2 - Wombat Detailing”) help?
Individual tool subsections must have safety information for that tool.
There are also general safety guidelines for the shop, which should be included (depending on which parts of the shop the class uses). (Possible TODO: turn these into inclusions?)
There may also be specific safety guidelines for the class (but not tool-specific). These can be included in the introduction.
We need a good pattern for discriminating between tools that have the smae name; for example, we have a drill press in both the metal shop and the wood shop.
This pattern is leads with a signal for the shop area:
…but gets noisy when lots of metal shop tools are listed together (on a clearances list, etc.).
This pattern leads with the tool name:
…and I think makes more sense for class handout use, given that the classes are going to be confined to one area.
The important question: what places in the Protohaven information architecture have a unified tool list? What's the best way to disambiguate in those places?
(The Tools and Equipment wiki page doesn't help answer this question at the time of writing.)
(The Tools and Equipment page on the Protohaven website (https://www.protohaven.org/equipment/) uses the first format, above)
TODO: update and reorganize this so it includes discussion of the student_guide/member_guide split. Specifically:
The draft guidance for class handout structure is as follows.
(Inclusions are parts of the document that are imported from a separate file, to help keep the information consistent across all classes.)
The Resources and Acknowledgements sections can be included as needed.
The draft guidance for tool subsection structure is as follows.
Not every subsection will be required for every tool.
Sometimes, the basic operation section may need to include an extra subsection for a Special Topic - a detailed discussion of something specific to that tool. Special topics should be included in the sequence of the workflow where it makes more sense (if the procedure in the special topic needs to happen before using the tool, but it before the “Use” subsection, etc.).
The draft guidance for software subsection structure is as follows.
Not every subsection will be required for every piece of software.
The Help and Tutorials section should point the student toward materials that will help them learn about the software: YouTube videos, starter guides, tutorials, etc.
The draft guidance for concept subsection structure is as follows.
There is expectation of a consistent structure here; concept subsections should include whatever informatino is needed to help the student use the tool.
These materials are prepared with Typst, an open-source document preparation system that turns text-based markup files into PDF output.
Using Typst has benefits: it's appropriate tooling for paginated documents (which we want, if we want to print out physical copies for students), and supports content reuse.
At the moment, the document set supports content reuse in two ways. A classroom document can import glossary terms from a common pool, and a classroom document can import relevant shop tool subsections. When updates are made to tool subsections, classroom documents can be easily rebuilt to pick up the changes.
The source files for the document set in version control, as part of the monorepo printed_materials in the Protohaven GitHub organization:
These drafts are licensed CC BY-NC-SA for the moment. This can be changed. Also, we want to make sure we're not using content under copyright by others for these materials.