Should we have a supplementary spec template for proposals?

[gregsdennis]

Since we've decided that new feature proposals will be defined in external documents, should we have a template document?

[gregsdennis]

Part of https://github.com/json-schema-org/json-schema-spec/issues/1444 will be extracting some keywords into their own documents. If we can just go ahead and do one, and then I can take that an make a template from it.

[Relequestual]

I see the document's purpose as two fold. Firslty, to convince others beyond the champion and proposer (which may be the same) that it has value, and secondly, to allow implementers to implement.

It might make senes to have two individual documents for each proposal. There will be a need for tests later, so each proposal is going to be a folder anyway and not just a single file.

This relates to https://github.com/json-schema-org/json-schema-spec/pull/1449#issuecomment-1759303793 and I think we need further discussion to understand and define the requirements and purpose of a proposal.

[gregsdennis]

The proposal document (as I originally envisioned it) has two audiences:

• Business/mgmt, who need to be convinced by their devs that an experimental feature is worth including in their code. This is critical to adoption of the experimental feature.
• Devs, who need to know how the feature works. This would describe the changes to the spec documents (core & validation) that would need to be made to include this feature.

While this is two different ways of describing the feature, I believe they should co-exist in the same document.

In #1450, @jdesrosiers split my single document into two: one for the reasoning behind the feature and one to describe the feature.

However in re-reading the comments in that issue, I think some things were being conflated. I believe Jason was wanting an additional internal document that served as a sort of ADR. An ADR would contain additional information that doesn't need to go into the proposal:

• summary of the discussion & its participants
• alternatives considered with pro/con lists
• reasoning why we chose the solution we did

In making the changes, he broke out what I had included for the "business" audience thinking its purpose was more akin to an ADR, but I think these are separate things. Business/mgmt doesn't need to know the things that go into an ADR, but they do need to have a plain-language summary of the feature. Further, managing the feature description(s) in separate documents (one for business, one for devs) I think is inconvenient.

I propose possibly two documents:

• a public-facing feature description document as I had originally posted in #1450, which includes both the high-level description and the spec changes
• an internal-use ADR-style document (maybe just an actual ADR)

~Secondly, do these really need to be in the same PR? Maybe we add a requirement to the process that a concept must have an ADR written and accepted before the proposal is written. That would be an official statement of "yes, this deserves to be a built-in feature."~

EDIT I've reconsidered this last paragraph. Please see my comment below.

[gregsdennis]

For the purposes of extracting existing features in order to move us toward the first stable release, I could write a single ADR that includes them all.

[gregsdennis]

We'll probably also want an ADR (or amend the existing one) if we decide to reject a proposal to explain why.

[gregsdennis]

Secondly, do these really need to be in the same PR? Maybe we add a requirement to the process that a concept must have an ADR written and accepted before the proposal is written. That would be an official statement of "yes, this deserves to be a built-in feature."

Thinking about this again, a feature could go through changes between entering the proposal/experimental stages and being promoted to stable. I think it makes more sense to have an ADR draft as part of the proposal, and then it's finalized when the proposal is promoted. This way, the ADR can contain all of the relevant details.

[jdesrosiers]

Business/mgmt, who need to be convinced by their devs that an experimental feature is worth including in their code. This is critical to adoption of the experimental feature.

Could you clarify this audience for me. I think of the main audiences as implementers and schema authors. We want implementers to build it and we want schema authors to use it. By "code" do you mean "schemas"? Is this about convincing business/mgmt to use the feature in their schemas or convincing business/mgmt to implement the feature? I'm not sure the latter makes sense as most implementations are individual projects, but I want to make sure I understand you correctly. Is the idea that because the feature is experimental, there is some risk to use it and therefore requires approval from business/mgmt and you want to speak to that concern?

[jdesrosiers]

I propose possibly two documents:

Sure. Let's try it and see how it comes out. I do think two documents is necessary, but I could have had the balance wrong in my initial proposal.

[gregsdennis]

Business/mgmt, who need to be convinced by their devs that an experimental feature is worth including in their code. This is critical to adoption of the experimental feature.

Could you clarify this audience for me. I think of the main audiences as implementers and schema authors.

Yeah, so I see two groups, but the delineation is slightly different.

• Business/Mgmt - This group will primarily be concerned with risk management. "What is the risk of adopting an experimental feature into our code base? Can the problem we're having be solved some other way that doesn't incur this risk?" I expect a developer / schema author would want to use an experimental feature but would need to get approval from their superiors. (E.g. they may have a policy against using pre-release libraries.)
• Technical people
  • Developers / Schema authors - Our end users. They want to use the experimental feature.
  • Implementors - We rely on this group to make experimental features available to the developers / schema authors.

I think the devs, authors, and implementors will all be interested in the same portion of the proposal: the technical bit. They want to know what the feature does, how it does it, and how they can use it properly.

But the business/mgmt group doesn't care so much about the techincal stuff; they're trying to assess risk and whether the devs really need the feature. I see the summary as a sort of sales brochure that the devs can take to this group. The summary should be plain English that states the problem and the (decided) solution; this should be a "why you should use this feature."

Further, I think having both this "sales pitch" and the technical stuff in a single doc means that the devs only need to download a single file, and they have both parts.

Regarding the alternatives, I agree that stuff like that is really internal documentation, and we don't need to include it in the primary doc.