Table of Contents
Class Materials
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.
Drafts
Drafts in Progress
Feedback Goals for Drafts
While working up comments on these drafts, there are three things I'd like us to think about:
- Student Needs
- Teaching Goals
- Workflow Notes
In each of these cases, I am interested to know about:
- Things we should fix
- Things we should keep
Student Needs
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:
- Safety warnings to keep students safe
- Usage notes so that students don't miss any steps (that they may have forgotten)
- References so that students buy appropriate consumables, materials, etc.
Teaching Goals
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.
Workflow Notes
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:
- Marked up printed copies
- Annotated PDFs
- Typed up notes with citations (“in the second paragraph of page 4, fix the following…”)
- …in reasonable formats: (Word files, google docs, text files)
- …in unreasonable formats: (Sky writing, cuneiform tablets, Morse code tubas) (but it may take me longer to process them)
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?
Content Notes
Distributing Safety Information
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.
Tool Disambiguation
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:
- Metal Drill Press
- Wood Drill Press
…but gets noisy when lots of metal shop tools are listed together (on a clearances list, etc.).
This pattern leads with the tool name:
- Drill Press (Metal)
- Drill Press (Wood)
…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)
Structure
Class Notes Structure
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.)
- Welcome
- Shop Rules (inclusion)
- Tool Status Tags (inclusion)
- Filing a Tool Report (inclusion)
- Class Safety Notes
- Introduction
- Learning Objectives
- Terminology (individual terms are inclusions)
- Tools Relevant to the Class
- Tool Subsection (inclusion)
- Tool Subsection (inclusion)
- Tool Subsection (inclusion)
- Resources
- Acknowledgements
The Resources and Acknowledgements sections can be included as needed.
Tool Subsection Structure
The draft guidance for tool subsection structure is as follows.
- Tool Name
- (Intro paragraph: what the tool is for, etc.)
- Notes
- Safety
- Common Hazards
- Care
- Use
- Consumables
- Tooling (recommendations for bringing own tooling/parts: blades, bits, cutters, etc.)
- Materials (what can and cannot be worked with the tool)
- Parts of the Tool
- (Annotated Image)
- Part Description
- Part Description
- Part Description
- Basic Operation
- Setting Up
- Workholding
- Using the Tool
- Cleaning Up
- (Special topics)
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.).
Production Notes
Document Production Software
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.
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.
Version Control
The source files for the document set in version control, as part of the monorepo printed_materials
in the Protohaven GitHub organization.
Licensing
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.