Each exercise can have approaches associated with them, which describe the different ways in which an exercise can be solved.
Approach
An approach should explore how an exercise can be solved a certain way.
- Its contents should either:
- Explore an idiomatic approach
- Explore a non-idiomatic, but interesting approach
- Start with a (full) code sample
- Liberally use code samples in the rest of the document
- Feel free to dig deep into the topic
- Link to useful resources (e.g. documentation)
- The snippet should showcase the core of the approach
- A maximum of 8 lines can be used
If you'd like to compare different approaches, please write an article.
Approaches overview
- Give context to the problem
- Describe important points (e.g. gotchas) that apply to all approaches
- Discuss the most idiomatic approaches
- Each approach should start with a snippet illustrating the approach
- Keep the content fairly high-level
- Detailed information should go into a standalone approach page
- Link to the standalone approach page for more information
- Discuss how to choose between the approaches
- What are the trade-offs?
- Are some approaches better suited for specific use cases?
General considerations
- Some languages have different ways of writing the same thing. If some of that syntax has only become available in more recent versions of the language, consider using the "old" syntax. This makes it more likely that students will understand the code.
- Alternative syntax can be shown in the approach document
- If your language has a recommended style guide, follow those guidelines (where possible)
What exercises to write approaches for?
In general, Practice Exercises are more suitable to write approaches for, as they usually can be solved in multiple ways.
For Concept Exercises, discussing the exemplar approach might be interesting. For example, you could show how the concept being taught makes certain code easier to write.
Configuring
Make sure to set the approaches.snippet_extension
field in your track's config.json
file.