Draft Features - accessibility

[cmheazel]

It is difficult to get developers to implement draft features because we don't have a single authoritative document for the proposal. How do we fix this?

[tedepstein]

Discussed on today's TSC call.

My thoughts:

• Single Markup doc is better.
  I agree that having a single markup document that represents the current state of the draft feature under discussion would be a very good thing. Even in cases where we haven't made the draft public, but it's a substantial and complex new thing being proposed (e.g. alternative schemas, overlays, traits), if that thing takes the form of an issue, as it currently does, people will have a hard time finding the part they should pay attention to, and a hard time being comfortable that it's safe to ignore all of the other accumulated comments in that issue.

• Track individual issues against a draft proposal.
  Also, once an issue gets a lot of comments, it's difficult to keep track of all of the sub-issues that have been raised in those comments. It's an extra burden on readers and contributors to have to keep combing through comments to find what's relevant and/or what's still under discussion vs. already resolved. Personally, I am reluctant to start piling on new questions or concerns on an issue that already has a sprawling mass of comments.

• More prominent list of draft proposals open for comment, ready for implementation.
  If we want to draw the community's attention to draft proposals, encourage comments and invite POC implementations, It would really help to have a dedicated page for this, and prominent links to that page. The page should have:

  • A list of active draft proposals, each with a link to markdown doc, and with a little explanatory blurb or sentence about each one.
  • A brief explanation of the draft proposal process.
  • A call to action going out to the community, asking for comments and test implementations.

@MikeRalphson proposed GitHub Projects as a way to help organize issues and tasks around a particular feature we're working on. Seems well worth a look.

I'm sure there are many other things we could do bring more energy into the draft proposal process. Hackathons came up on the call. But maybe we can raise those as separate issues, so we don't expand the scope of this issue too drastically.

[earth2marsh]

GitHub Projects is an interesting idea. We should consider that. Myself, I caught myself wondering today whether we do enough to capture the use cases up front when we're defining the solution to a problem. I'd love to see us work that into our process better.

[cmheazel]

I have an AsciiDoc for Alternative Schema. Just let me know where to put it (polite answers only please).

[cmheazel]

@earth2marsh I agree that use cases would be valuable as well. Each use case should be a discretely resource identifiable via a URL. Do we have a place for them?

[MikeRalphson]

I have an AsciiDoc for Alternative Schema.

@cmheazel can we use GitHub-flavoured markdown in preference to AsciiDoc, as elsewhere in the repo?

[MikeRalphson]

Just let me know where to put it (polite answers only please).

@OAI/tsc I'd suggest something like /technical-notes/v3.0/draft-feature-alternative-schema.md if we'd like this in-repo on the master branch. An alternative is in the registry: http://spec.openapis.org/registry/draft-feature/alternativeSchema.html

[cmheazel]

@MikeRalphson I didn't know GitHub had a preference. I'll have to convert it. Might take a few days.

[cmheazel]

@MikeRalphson Can we create a separate directory for draft features rather than burying it under technical notes?

[cmheazel]

See Pull Request #1868 for an example using Alternative Schema.

[handrews]

We now have a top-level proposals directory, plus various potential features are registered as extensions on spec.openapis.org. Closing - please open new issues if there are specific gaps we need to address.