Closed Insti closed 1 year ago
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.
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).
The README seems like a logical place to link to each doc and describe its purpose.
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.
I mostly add documentation after having a conversation with a contributor or maintainer, and discovering that we're missing something.
There are 6 subdirectories of this repository.
But what is the difference between all these?:
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"?