Document the various rules on the website

[awwright]

The specification is, properly, a specification for implementation authors to refer to. This makes it rather verbose and technical, and hard to learn from.

So for a better general reference, the website should include a reference written for schema authors (instead of implementors), detailing various recipes, examples, gotchas, and links to the appropriate section from the normative specification.

This perhaps could be done in plain HTML or Markdown files in a "dev" branch. These changes are then pulled into the "master" branch and compiled as part of the merge commit. The process might go something like:

# Update branch
git checkout dev
git pull json-schema-org dev
# Merge in new material
git fetch remote
git merge remote/dev
git push json-schema-org dev
# Build and update 'master'
git checkout master
git merge --no-ff --no-commit --strategy=theirs dev
make
git commit
git push json-schema-org master

This way build products are kept isolated from the "dev" branch.

[Relequestual]

I'm all for using gitflow (http://nvie.com/posts/a-successful-git-branching-model/).
Already follow that methodology on a daily basis.

As for the issue at hand, sure, sounds like a good idea. I'm half tempted to resurect my old closed issue #1 ... any feedback on it?

[awwright]

I would break the issue down into smaller chunks than #1 has. Then fix the problems, then implement new stuff.

[Relequestual]

Feel free to expand and do so on the issue =] Then we can create new issues as and pick up work as time allows.

[awwright]

Update: I've got a repo that does all this, I just need to add content to it then make a PR

[epoberezkin]

@awwright:

So for a better general reference, the website should include a reference written for schema authors (instead of implementors), detailing various recipes, examples, gotchas, and links to the appropriate section from the normative specification.

I think that by trying to create it we distract from the main goal and only add to the confusion. There are many reasons why this community should avoid creating any other references or tutorials apart from I-D and let third parties (or individual community members) do it as their own projects:

1. Resources. Standard evolution takes a lot of time and if we add some other reference to the mix to write/discuss/approve/maintain it will add to that time.
2. Confusion. In case of any discrepancy, users would see such reference as the source of truth, while I-D should be the only source of truth.
3. Contributions from others. By creating an "authoritative" reference you devalue any efforts to create alternative references and demotivate other people to distribute their content in other places on Interwebs, in such way reducing the spread of knowledge about the standard.

The site should contain the list of links to high quality resources (references, tutorials, etc.), as it already does, in the same way it has a list of validators. At the same time the site should make it clear that such documents can be inaccurate and refer to I-D as the source of truth.

We have enough contentious issues both on the substance and on the process to add discussing any references to the mix. @handrews @Relequestual ?

[awwright]

@epoberezkin Those are good points.

I still don't think it's that much of a problem... I think we can kind of consider the website a community resource - it's easy to update by PR. Numerous projects put a "edit file on GitHub" link on their website documentation, soliciting updates from users.

Regarding confusion, ultimately, the implementation is the "source of truth" (in a sense). And the implementations would still refer to the specification. The documentation, in this understanding, would itself be an implementation (in a sense).

The specification, meanwhile, describes a lot of practices that aren't good practices, and examples are sparse. So we are sort of balancing the risk of getting something wrong (the same risk that any implementation has), versus improving the quality of written schemas and promoting their use. I think it's in our interest to help promote JSON Schema this way.

Other standards maintain an official reference. HTML publishes an official companion document for HTML authors (as opposed to implementors... or at least until 2013 when they integrated it into the spec itself, somehow). HTTP publishes their spec formatted as HTML. JSON itself has http://json.org/.

[epoberezkin]

I agree that it is quite common. I can add React to this list, e.g. But they either through a lot of resources to it (Facebook...) or have a very small (JSON) or stable (HTML) thing to describe... We are in neither of these categories I am afread...

I really believe we need to maintain awesome-json-schema repo, add it to to https://github.com/sindresorhus/awesome and that would motivate people to add more resources to it.

I have nothing against you doing some additional resources, I've done a couple myself (reference, articles), but I'd rather they all remain unofficial and linked to.

Not going to fight it though :)

[awwright]

@epoberezkin It appears the question is how far do we want to take this.

Maybe it's not appropriate to write a full tutorial. I think we can describe a little bit about the philosophy behind JSON Schema, and things like that.

But I certainly think we can at least take the existing language in the spec and make it pretty, remove information irrelevant to authors, and maybe add several examples.

[Relequestual]

I'd like to use Stack Overflow documentation site for adding documentation on how to use JSON Schema rather than adding it to the website. My preference, however we are blocked... http://meta.stackoverflow.com/questions/340038/everyone-can-contribute-to-documentation-but-i-cannot-commit-to-this-proposal Will see what the response is.

It's also unclear if this issue is regarding the documentation on how to use JSON Schema, or how to use the repos to contribute to JSON Schema.

[Relequestual]

Closing this issue because we inherited https://github.com/json-schema-org/understanding-json-schema some time ago.