Good sample code for teaching has the right mix of real world applicability and extendability while being easy to learn on.
Once you’ve done that, it’s time to think about how to challenge your most dedicated learners. Here are a few patterns I’ve used for designing advanced challenges.
You can use these ideas for tutorials, instructor-led workshops, or even books and printed materials. I’ve used these ideas to teach technical software and cloud infrastructure topics, but you could use many of the same ideas for art, music, or other domains.
The short list
Here’s a short description of each. Or read the details in the next section.
- Build from here • Add a feature on top of the existing demo application
- Build the demo from scratch • Start from a blank file and code the parts of the demo that were given to you as a starting point
- Scale • Enhance the demo with at least two of a resource that is used once, or scale way up with 10x or more
- Collaborate • Build the same demo together with one or more other people
- Use together with other tools • Implement an additional tool to the demo
- Refactor with best practices • Go over a part of the application that was coded for ease of learning but needs to be improved to follow best coding practices
- Refactor with security • Do the same but for security best practices
- Go to staging or production env • Deploy the application to any compute resource or CDN outside of your local machine
- Add monitoring or observability • Instrument the demo application with monitoring tools
- Explain it to someone else • The Feynman method: explain what you’ve just learned to a real or imaginary person
- Document it • Write instructions to developers, operators, or end users of the application
Detailed descriptions
Build from here
This is the standard advanced challenge: keep building on top of the demo by adding more functionality. Example: If the demo is a shopping cart and you’ve implemented the ability to add items to the cart, then add a feature where the shopper can delete an item from their cart.
Build the demo from scratch
Most applications created for learning include a non-blank starting point to make it easier for the student. For this advanced challenge, the student builds that starting application for themselves. Example: If you were given a pre-populated database (including tables and other schema), start over with a blank database and build the table definitions and sample data.
Scale
Tutorial applications usually involve a small amount of data and a single compute instance (your local machine). But production use cases involve many rows of data and a flood of compute. Expand your experience by scaling up. Example: You’ve built a Terraform configuration that provisions a single cloud compute instance. Now create 10 instances. Example: You’ve written an R script that consumes 100 lines of data from a CSV, now modify it to process 10,000,000 rows of data.
Collaborate
Tutorials are often coded alone; complete this challenge with a friend. Example: Build a new feature or re-implement an existing feature with the help of a peer. Bonus: use GitHub, Bitbucket, or another shared code platform to build the feature around standard collaboration workflows like pull requests and code reviews.
Refactor with best practices
Tutorial applications are often written to be verbose and explicit so that beginners can learn from them more easily. For this challenge, refactor the application with best practices for a production environment. Example: Refactor the application for maintainability, DRY, SOLID, or other coding best practices. Example: Create an installable package with the demo app using your language’s packaging framework (Python pip, Ruby Gem, R package, NPM package, etc).
Refactor with security
This one is debatable because in many cases, it’s better to never teach a student to do something that might be insecure (such as hard-coding API keys into a code file). But if the application you’re teaching from could be made more secure in any way, ask the student to improve it. Example: Remove sensitive data from code files; store in ephemeral ENV variables instead. Example: Store sensitive material in an encrypted data store like HashiCorp Vault.
Deploy to production
Tutorials are often run on one’s laptop or on a provided lab environment, but production systems are run in the cloud on on some kind of external compute. Example: Create a container, deploy to Kubernetes, spin up an ECS instance, or otherwise run the application somewhere outside of your local machine.
Add monitoring or observability
Even a simple tutorial application can generates logs, traces, and other analytics. But you can’t learn from them unless you collect them. Example: Instrument the application with Prometheus, Datadog, or another service.
Explain it to someone else
Explaining a concept to someone else isn’t about passing on knowledge as much as going through the experience of forming thoughts in your head to understand it yourself. Example: Describe what you learned to a desktop rubber duck or to another human (in a technical or non-technical way).
Document it
I use Bear app for personal notes. One of my most frequently used tags is study-notes where I write notes to remember later and to understand now. Example: Add to public open source documentation or just a local doc for your own learning. Example: Sketch a picture or diagram that explains the concepts, architecture, or workflow of what you just learned. See Maggie Appleton on Drawing the Invisible for inspiration.
