Track-specific content in exercise READMEs is easy to miss

[kytrinyx]

@DouglasBrunner commented in https://github.com/exercism/xjavascript/issues/33#issuecomment-54010058:

I started in Haskell before Javascript and didn't think to read further since the instructions seemed to be the same.

Since the Haskell track doesn't use skipped/pending and the entire top section was the same, it was easy to scan the beginning and decide that there was nothing new here.

I suggested that maybe we could move the track-specific stuff higher up, but @DouglasBrunner observed (quite rightly) that this would likely break the flow of the README, and suggested that we add a table of contents. E.g.

1. Introduction
2. General Instructions
3.  Language Specific Instructions
3.1. Running Tests
3.2. Common Problems
4. Restrictions
5. Source

Another suggestion was to update the "Running the Tests" section of http://exercism.io/languages/:slug/tests (e.g. http://exercism.io/languages/javascript/tests).

And yet another:

[W]hy not mention modifying the test suite in the test suite itself? I personally always look at the test suite before doing an exercise. It would only require one or two lines of additional code. I'd be willing to help out with that change if you're interested.

And finally, we could add a comment at the top of the first test suite in the language track (or the first test suite that uses pending/skipped tests) which explains how to proceed.

Thanks to @joelwallis who noticed this discussion hidden away in a solved support request.

Thoughts?

[Insti]

I'd be concerned that a table of contents would just be another bit of text everybody would ignore.
The track specific stuff is already as high as it can be, and how it is organised is up to the tracks themselves.
It would be possible to do some interesting things by getting creative with the HINTS.md and TRACK_HINTS.md files.

Track level options for readme differentiation

The stuff after the problem description can be adjusted on a per track basis by editing:
exercises/exercise_name/HINTS.md
and/or
exercises/TRACK_HINTS.md

How the readme is constructed

Exercise specific description.md (from x-common repository)
exercises/exercise_name/HINTS.md (from language repository)
exercises/TRACK_HINTS.md (from language repository)
Source (from x-common repository metadata.yml)
Submitting Incomplete Problems (hardcoded Exercism wide string)

Things can change if we find a better way.

Information correct as at 18 April 2017

[kytrinyx]

Here's where the README construction is documented: https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/fixing-exercise-readmes.md

[kytrinyx]

And here is where it's implemented:
https://github.com/exercism/trackler/blob/cf7057d6be587b2e144d97eac4820b9c10275c08/lib/trackler/implementation.rb#L67-L79

[kytrinyx]

We've completely reworked the exercise READMEs so that each language can lean on shared documentation, but veer from that and customize where necessary.

Please see the documentation about this at: https://github.com/exercism/docs/blob/master/language-tracks/exercises/anatomy/readmes.md

If you rework some of the documentation in a track and find that your explorations would be helpful to the tracks in general, I'd really appreciate it if you open an issue here in the discussions repository to share your observations and findings.