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.

• intro_to_lathe
• intro_to_large_format_lasers
• intro_to_metal_shop
• millwork_and_joinery

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

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.

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:

• 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?

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:

• 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)

TODO: update and reorganize this so it includes discussion of the student_guide/member_guide split. Specifically:

• student tool guides are to be kept simple to aid student learners
• member tool guides handle specific scenarios/materials, corner edge cases (unless they lead to unsafe conditions - students need to know about those)
• Member tool guides start with a Quick Reference section that allows for fast lookup of important information for that tool: dimensions, calibrations, limits, consumables, etc.

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)
  • …
• Software Relevant to the Class
  • Software Subsection (inclusion)
  • …
• Concept Relevant to the Class
  • Concept Subsection (inclusion)
  • …
• Resources
• Acknowledgements

The Resources and Acknowledgements sections can be included as needed.

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.).

The draft guidance for software subsection structure is as follows.

• Software Name
  • Overview
  • Download
  • Help and Tutorials

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.

• Concept Name
  • Description

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:

https://github.com/protohaven/printed_materials

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.