Documentation layout is confusing to me.

[Insti]

There are 6 subdirectories of this repository.

• about Seems to cover what the project is about and an overview of the components. That I understand.

But what is the difference between all these?:

• contributing-to-language-tracks
• contributing
• language-tracks
• maintaining-a-track
• you-can-help

What seems to be covered in each one appears fairly arbitrary to me, and the directory names appear to overlap a lot.

contributing-to-language-tracks, language-tracks, maintaining-a-track (How are these different? where'd "language" go?)

contributing-to-language-tracks, contributing (to things that aren't language tracks?, what about problem-specifications that the language tracks rely on? or the other areas like the website and configlet and trackler/api where should they be documented?)

you-can-help how is "helping" different to "contributing"?

[ErikSchierboom]

I agree with @Insti that the current setup definitely is confusing. Something can be said for splitting contributing to a track from maintaining a track, as the latter does involve the former, but not vice versa.

[rpottsoh]

I also agree with all of this. I find it very difficult to locate documents that I recall reading at one time, but now have been relocated or maybe the contents moved to another place. When I would like to cite a document to someone I end up stuck. Unfortunately I don't have ideas on how to resolve this. Perhaps some sort of TOC that starts at the repo level and then drills down maybe would help shine some light on how the documentation flows (or doesn't flow).

[tleen]

The README seems like a logical place to link to each doc and describe its purpose.

[kytrinyx]

I'm aware that it's confusing. I've generally been adding documentation and trying to find groups of content that make sense together, and haven't found the final location for anything.

There are two types of content so far.

• reference documentation: by topic, as complete and detailed as possible (e.g. "track configuration") https://github.com/exercism/docs/tree/master/language-tracks/configuration
• guides: you have a starting point, a document that gives you a mental map of how to process things, which links out to reference documentation along the way. E.g. https://github.com/exercism/docs/blob/master/language-tracks/launch/README.md

I mostly add documentation after having a conversation with a contributor or maintainer, and discovering that we're missing something.