Write the Docs: Robert Lehmann – Self-Directed Learning Material

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Robert focused on how to write good learning material. We all suffer from ed-tech amnesia, in Robert’s words. There’s a huge body of research on how to teach people and how they learn material. In researching this talk he found that while there’s a huge body of material it is wildly arcane to us as technical people.

Robert works at the Open Tech School where they work to teach students programming. The workshops are done collaboratively with lots of hands-on coaching.

The first step in learning and collaborating is defining clear goals. You need to know where you want to go with the material; beginning with the end in mind helps greatly. There’s a difference between tutorials and references. References may seek to exhaustively document an API while tutorials consciously explain a single concept with an end goal defined.

Collaboration, though, can kill cohesion. With many people involved you have to actively protect the scope of learning material. At the Open Tech School they have someone who acts as the champion of learning documentation and they seek keep work tied closely to learning objectives.

When you use the right tools and lightweight markup you can lower the barrier to learning. For the Open Tech School this means using Jekyll and hosting files on GitHub Pages.

One thing that they haven’t found a good solution for is dealing with dependency hell. When teaching people how to code you run in to issues where the prerequisites for solving a given problem can involve setting up handfuls of other, irrelevant, dependencies. When teaching kids they’ve tried using system images that bundle those dependency requirements so students can write code and have it run right out of the box, mostly.

Another thing they have struggled with in their material is the amount of repetition. Repeating things is good, but at the same time you want to be concise so that students don’t skip over repeated material.

One guideline that is extremely useful for new coaches is to tell them the keyboard of students is made of lava. Too many new coaches cannot suppress the impulse to just fix one thing for the student. The problem is that this disrupts the student’s flow and attention. On top of that nudging new coaches to use socratic questioning can greatly help. Your students will benefit if you don’t just give them the answers.

At the Open Tech School they’ve found that feedback is great but that it’s mostly positive from students. Instead they focus on asking the coaches for feedback on where students struggle. It helps them spot the gaps and shortcomings in their documentation and learning material.

Finally, they’ve published all of their coaching guidelines.