Feedback on FAQ for draft-06 Hyper-Schema changes

[handrews]

There's a lot that's gone on with Hyper-Schema between draft-luff-json-hyper-schema-00 and draft-wright-json-schema-hyperschema-01, and the "why" of the changes isn't always obvious. So I wrote a FAQ about it (assuming that currently opened PRs are approved and no further changes are made):

https://github.com/json-schema-org/json-schema-spec/wiki/FAQ:-draft-wright-json-schema-hyperschema-01

Please comment here on what needs to be improved!

[handrews]

@awwright @jdesrosiers @Relequestual @geemus @slurmulon @Anthropic @dlax
comments most appreciated!

[dlax]

Overall, I think this is a good idea to have a FAQ and most of the content is useful. On the other hand, I'm not sure all the contents would fit in a FAQ and wonder if some items wouldn't be better suited in release notes.

Q: So how do I indicate which HTTP methods are supported on a link?

I think we should mention Allow header to be retrieved from either the GET or an extra HEAD.

[Relequestual]

This looks useful. Great job.
I scanned it briefly, but I should be able to give it a proper review at some point...

[handrews]

I'm not sure all the contents would fit in a FAQ and wonder if some items wouldn't be better suited in release notes.

That feedback is too vague to be actionable :-) Also, I don't have time to manage a bunch of documents, and it will be hard enough to get people to read one much less two or three. I don't care what we call it, but this is the document.

I think we should mention Allow header to be retrieved from either the GET or an extra HEAD.

That's not what people mean when they ask those questions, they know about the header already and are only interested in how to put the information in the schema. We've been through enough discussions on this topic to know the pattern, and the FAQ is sprawling enough as it is without getting further into protocol usage advice.

[dlax]

That feedback is too vague to be actionable :-)

Fair enough.
What I had in mind:

• for people who just discovered and read the draft and have a question: answer should be in FAQ;
• for people with knowledge of prior version of the draft that want to know why things changed, answer should be in release notes.

The document currently addresses both use cases, which is probably fine as a first step. Thanks for putting this together.

That's not what people mean when they ask those questions, they know about the header already and are only interested in how to put the information in the schema.

Not sure this is true for everybody. For instance, json:api has a item about this in its FAQ: http://jsonapi.org/faq/#how-to-discover-resource-possible-actions
But okay, let's keep it as is.

[handrews]

for people who just discovered and read the draft and have a question: answer should be in FAQ;

That would be a reasonable expectation. I didn't want to get into too many more topics because a.) I've been writing a huge amount of documents on hypermedia between this project and my official day job work, and b.) if a page gets too long no one reads it. Or more accurately, very few read it, and the people who hate reading long things complain. A lot. (I'm super-tired of it over the past several years; I know I'm verbose, if someone wants to edit it to tighten the language be my guest)

The document currently addresses both use cases,

Yeah, it's really a FAQ about the migrating to the new draft. There is already a thing called "Release Notes" in the actual draft, so calling this "Release Notes" would be confusing. But maybe FAQ is also confusing. Open to other title suggestions.

which is probably fine as a first step. Thanks for putting this together.

Thanks & you're welcome!

Not sure this is true for everybody. For instance, json:api has a item about this in its FAQ: http://jsonapi.org/faq/#how-to-discover-resource-possible-actions

Meh, I was probably overly cranky about this last night.

I'm mostly worried about getting into a really large topic of runtime HTTP interactions in the FAQ. It's really, really hard to keep these things focused, and starting to talk about that makes people ask for a more thorough treatment and I just can't right now.

[Relequestual]

Your FAQ page is just TOO LONG...

;)

But no, it's actually useful, so thanks.

[handrews]

@dlax I did make a note of the Allow response header and also made the title more about migrating from the old to new draft than a general faq. I think that takes care of all feedback so far so I guess I'll close this. It can be re-opened if more feedback comes in, or people can just open a new one.

[geemus]

Sorry for the late response (vacation last week). 👍

[handrews]

@geemus no worries thanks for looking it over!

[Anthropic]

@handrews I like it, is it linked from the webpage, should it be if not?