json5
Explain use cases front and center
To this date, many people's initial reactions to JSON5 are still quite negative because they think JSON5 is aiming to replace JSON for machine-to-machine communication (e.g. APIs, databases).
We already say "JSON for humans" in the title, but we can probably do a better job of explicitly and proactively clarifying that JSON5 is meant for use cases where humans write/edit/maintain JSON by hand — e.g. config files, test cases, etc. — and not use cases where computers generate JSON for other computers to consume!
It might also be worth clarifying that the default JSON5.parse API of this library returns the core data being specified, but other libraries exist that can provide the full AST (abstract syntax tree) including comments, line breaks, etc., for formatting and other similar use cases.
WDYT @jordanbtucker? I can take a stab at some wording here but wanted to get your thoughts too. =)
Ooh, while we're at it, maybe we should also mention prominent examples of adoption front-and-center on the readme too? E.g. Apple, Babel, Next.js, etc.
I know we have our "In the Wild" wiki page. I'm thinking that our readme and json5.org homepage can prob do a better job of marketing, not just defining & documenting. =)
Choosing to call it JSON5 unfortunately lent to the confusion. e.g., previous to HTML 5, HTML was just known as HTML to most people. This gives a very strong impression to people that JSON5 is an evolution, or "the next version of" JSON, meaning most people will assume it does address those computer-to-computer use cases.
IMO, the format needs a different branding altogether.
Yeah, fair point! Still, I'd love to not open the rebranding can of worms for now; I bet there's plenty we can improve through just some better upfront explanations. =)