Add more approaches guidance (exercism#398)

Add more approaches guidance Co-authored-by: Katrina Owen <katrina.owen@gmail.com> Co-authored-by: ee7 <45465154+ee7@users.noreply.github.com>
kumargejara · Oct 26, 2022 · 41fe3d0 · 41fe3d0
1 parent fba86ef
commit 41fe3d0
Showing 1 changed file with 15 additions and 5 deletions.
diff --git a/building/tracks/approaches.md b/building/tracks/approaches.md
@@ -10,22 +10,32 @@ An approach should explore how an exercise can be solved a certain way.
   - Explore an idiomatic approach
   - Explore a non-idiomatic, but interesting approach
   - Contain a meta discussion (e.g. comparing the performance of approaches)
-- Include code samples
+- 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
 
-## Approach overview
+## 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 show a snippet illustrating the approach
-  - Keep the content fairly high-level
-    - Link to the idiomatic approach for more information
+- 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](/docs/building/tracks/practice-exercises) are more suitable to write approaches for, as they usually can be solved in multiple ways.