Structuring Code Tutorials

The best way to teach technology is by using technology. Gone are the days of heavy, boring textbooks – our era is one of interactive, self-paced, engaging instruction!

I have a few suggestions for how to make your digital curriculum as effective as possible.

Use questions as headings:

  • What is Go?
  • What is the difference between Go and Golang?
  • Why should I learn Go?

Use short paragraphs.

They should be bite-size chunks of 1-3 sentences that are easy to distinguish on mobile devices.

Utilize lists, which can:

  1. break a larger idea into smaller points
  2. group related facts together
  3. help readers remember important information

Use tables, which are great for organizing reference material and clearly comparing items property by property.

Include plenty of code snippets. It’s especially helpful to compare and contrast code snippets:

  • What would happen if we added this?
  • What would happen if we removed this?
  • What’s another way to solve this problem?
  • How would we fix this error?
  • Which of these approaches is more performant?
  • Which of these approaches is easier to read and maintain?

Embed interactives in the instructional content. These could be completely unique learning tools, or they could just be an embedded sandbox that the reader can play with:

Not all interactive content needs to be embedded. Students can read your instructional content from one tab or screen while following your instructions in another:

Additional interactives could include:

  • Multiple choice learning checks with guided feedback (feedback on both correct and incorrect responses that steers the learner toward better understanding)
  • Interactive checklists that save state (localStorage) so learners can better manage their learning.
  • Terminology review flashcards

Check yourself with these three questions:

  •  Do I clearly explain what my readers are supposed to be learning so they can check their knowledge?
  •  Could a complete beginner understand this tutorial? If not, is my target audience clear?
  •  Do I link to external references for things I expect my readers to already understand or to learn elsewhere?

Finally, break your content into manageable pages! It is natural for readers to measure their learning progress by how many pages they’ve “completed” on your site. Break your concepts into separate pages to meet this expectation.