I saw for example that Collatz conjecture exercise, at least on Python, isn’t very well-documented:
It was easy enough to finish but I’ve been coding for a long time, including Project Euler in the past. I was looking through issues on the website but couldn’t find any for Python, yet I’m virtually certain documentation like in the Collatz example would not be considered up to snuff compared to other exercises. I don’t know if there’s a style guide or whatever to follow. I tend to pretty sparse with documentation myself and am unfortunately pretty new to TDD so any pointers would be appreciated.
Which part of the exercise in particular? Most practice exercise documentation is lifted straight from the problem spec. The problem specs need to be language-agnostic so they tend to be light on implementation details. Additionally, Exercism focuses on TDD so the docs intentionally do not spell out each and every requirement.
The most immediately obvious difference I noticed was between, say, the Collatz exercise and another I just finished, “Making the Grade”:
Each function is described in more or less detail and a signature is provided, I believe in a format that automated documentation tools can make use of. The Collatz exercise has only one function but no comments of any kind.
“Making the Grade” is what we call a concept or learning exercise (specs here). The extra signatures and instructions are there because the student is learning.
“Collatz Conjecture” is a practice exercise. Practice exercises (specs here) are open-ended and intended to challenge the student with a less specific problem to solve. With practice exercises, we expect the student to read the test files (TDD), and also problem solve around what is being asked of them.
So the two have different goals, and different support documents and intentions.
Edited to add: Concept exercises often have one (or very few) ‘correct’ solutions. Practice exercises have lots of solutions and students are encouraged to try lots of different approaches to them.