Implement Best Practices section

[anatoly-scherbakov]

Best practices

This PR is to propose some thoughts I had derived from discussions held in the issues of this repo. It adds a new informative section to the spec modeled after (and referencing) JSON-LD Best Practices document.

It would seem that the consensus of the group is a strong intention to keep YAML-LD and JSON-LD convertible from one to another using mainstream JSON and YAML tools. That means the proposed hard-wired $ ←→ @ conversion is not feasible.

As an alternative, a special context was suggested in a discussion, and that is implemented in this PR. I thought that adding it as a normative requirement would be a bit too restrictive — that was the main motivation to include a new non-normative section to the doc, to suggest this context just as a possible solution.

1. Do you think this could be part of the spec? Or perhaps it should be a separate document? My reason to add it here was to a) make it easier to manage all the efforts in the view that b) spec is currently quite small so perhaps adding one little section won't hurt it.
2. What do you think about the convenience context as a suggestion in the spec?

I will probably add a few more UCRs for other questions touched by this PR.

Thank you!

---

Preview | Diff

[gkellogg]

Please consider wrapping lines on natural boundaries, which make it easier to make change suggestions through GitHub.

Not sure I agree with all of the best practices you propose, but it's an interesting point of discussion.

[anatoly-scherbakov]

Line wraps added, thank you for pointing out.

[VladimirAlexiev]

@anatoly-scherbakov

proposed hard-wired $ ←→ @ conversion is not feasible

Agreed it cannot be the only or the default option.

But I think there should be an option sigil: or prefix_char: where I can pick my own: $ or _ etc

[OR13]

yaml supports '@', I don't think we should encourage additional sigils... but if we do, we better allow for '💎' to be used.

[gkellogg]

This PR was discussed in the 2022-07-06 meeting, and it was agreed to merge.

[gkellogg]

@anatoly-scherbakov I've added you to the team, which allows you to make branches within this repo. That way, it's easier for others to collaborate on your PRs. Please reconcile the conflicts in your branch and we can merge.