Update Readme #11
Update Readme #11
Conversation
radeksimko
force-pushed
the
update-readme
branch
from
d86838a
to
c18259a
Compare
|
|
||
| ## What editors this can be used with | ||
| Instead you can use the grammar through editors, editor extensions, or highlighting libraries which in turn may use this repository, for example: |
There was a problem hiding this comment.
| Instead you can use the grammar through editors, editor extensions, or highlighting libraries which in turn may use this repository, for example: | |
| In most cases you will use these TextMate grammars through editors, editor extensions, or highlighting libraries which in turn may use this repository, for example: |
There was a problem hiding this comment.
I'm curious what are the other cases here, in which end-users would want to use the grammars directly? Maybe it wasn't clear what I meant by "end-user" above - should I clarify that to "Editor end-user"?
There was a problem hiding this comment.
I think this can be resolved by splitting up this document as discussed in https://github.com/hashicorp/syntax/pull/11/files#r821403019
|
|
||
| * HCL - TextMate | ||
| * Terraform - TextMate | ||
| Generally you should never need to interact with this repository directly. |
There was a problem hiding this comment.
| Generally you should never need to interact with this repository directly. |
|
|
||
| We may consider distributing the grammars via a packaging system such as NPM in the future. | ||
|
|
||
| #### Grammar Mapping |
There was a problem hiding this comment.
This is a great deep dive into how this all works, but it is a lot of info to drop in a README we don't expect to have external help just yet, which will probably change a lot in the next few cycles. I think this probably is better suited in the development.md or in a CONTRIBUTING.md.
There was a problem hiding this comment.
We could cut it down a bit and move some content into separate files but there are different types of content which we should not conflate and probably not put into CONTRIBUTING nor DEVELOPMENT.
From my POV there are different personas we're targeting here (1) end-users of editors/websites, (2) maintainers of extensions/websites (3) contributors to our grammars
- (1) should generally never even need to know about this repo IMO, so we just send them away via links to extensions etc.
- (2) they need to know how to use this but the instructions IMO shouldn't be in DEVELOPMENT or CONTRIBUTING, more like
USAGE.md- as from their POV they're using it - (3) for these people we can put instructions into CONTRIBUTING.md (or development.md) as - these would be people contributing back to this repo e.g. to
hcl.tmGrammar.jsonorterraform.tmGrammar.json.
There was a problem hiding this comment.
I'm not tied to filenames, but from your response we appear to be in agreement that this README should be a landing page and not a catalogue of all the different sets of knowledge required to use the files in this repo.
Extrapolating from your thoughts, I think we need:
- README.md with sections briefly explaining the repo and the different types of uses cases. Each with links to get users/contributors where they need to go.
- USAGE.md document outlining expected ways to consume these files
- CONTRIBUTING.md document outlining what content we accept.
Since the goal of this PR is to get the project quickly to the point of unblocking other work, I'm fine with ticketing this as a follow up and merging this PR as is.
There was a problem hiding this comment.
👍🏻 created #14 to track the remaining work
Co-authored-by: James Pogran <jpogran@outlook.com>
The aim is to answer likely FAQ and make the repo ready to become public.
It is best viewed rendered: https://github.com/hashicorp/syntax/blob/c18259a3fdfcf2478bf45c72894165050be67ee2/README.md