I understand that Atom has inherited a poorly-specified legacy, filled with the evidence of many ad-hoc decisions, a fair amount of cargo-cult code, and so on. And despite the mess, it all has value worth nurturing. I am not trying to suggest that anyone gratuitously break old grammars or syntax themes.
What I'm suggesting is that, as a way to move forward, it would be beneficial to define a more rigorous policy / standard / API for syntax markup. This policy would have a lot in the way of SHOULDs and MUSTs and MUST NOTs, which could guide both new development (new themes, new grammars) and also help inform authors as they evolve legacy packages towards a more explicit common consensus.
But details notwithstanding, what I really want to understand at this point is if this kind of documentation is something that would be embraced by the core Atom team or just be considered pointless noise. I'm happy to contribute some of my time trying to codify whatever seem to be the dominant existing practices / the de facto API, if it wouldn't be wasted effort. (To be clear, I would have no problem if this isn't something the core Atom team wants; different folks have different priories and all that.)
More concretely, if I wanted to put together an inaugural PR to start this document, where (what path on what repo) is the best place for it to go?