Approaches

Learn how to write approaches for exercises

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.

Files

Each approach must add the following two files:

  • .approaches/<approach-slug>/content.md: description of the approach (see the docs)
  • .approaches/<approach-slug>/snippet.txt: snippet showcasing the approach (see the docs)

You'll then need to add or update:

  • .approaches/config.json: metadata for the approaches (see the docs)

Configuring snippet extension

You can also use a custom extension instead of the default .txt extension by setting the approaches.snippet_extension field in your track's config.json file. If set, the snippet file you need to add must be named .approaches/<approach-slug>/snippet.<approaches.snippet_extension>.