Old issues related to documentation

[colinleach]

There are several that suggest better exercise documentation: approaches, mentoring notes, etc.

• Write dig-deeper page for darts and talk about hypot #660
• Rational numbers wants an approaches and better instructions #652
• Convert remaining mentoring notes to dig-deeper pages #644
• Improve mentoring notes for difference of square #264
• [v3] Write a brief benchmarking guide #303

I don't disagree with what they say, but (based on past experience, preparing for 48in24) I believe that both the following statements are true:

• Approaches are a valuable addition to Exercism, and it would be good to have more of them
• If done well, approaches are a slog to write and a slog to review. Anyone who tries to create lots of them quickly loses enthusiasm.

Others are of course free to write what they wish, but in the coming months my focus will be on the learning syllabus.

[depial]

I found the approaches idea fairly interesting, so I might be up for working on some of those in the future. It might be nice to have with the concept exercises at least.

[colinleach]

That would be one option, though quite an unusual choice. I think the majority view is:

• Concept exercises are pretty focused, with few ways (ideally just one) to solve it, and step by step instructions.
• Practice exercises are more open-ended, and the community solutions are quite diverse.

For a taste of contrasting styles, maybe look at the relatively short docs that Bob wrote for Python (e.g. pig-latin) vs me digging into roman-numerals, or matching-brackets, which also has a performance analysis under articles/.

Entirely your choice, of course. In this context, anything is worth having.

[colinleach]

There's one thing you might enjoy about approaches. Whereas concepts are aimed at novices and need to be relatively simple, approaches can be as nerdy and technical as you like - few limits! With the provisos that we're not allowed to use $\LaTeX$, and graphs land you in all sorts of complications (light vs dark mode, guidelines on making them accessible to vision-impaired users, etc).