json-schema-org/json-schema-spec

Specification Flow could be improved (but what do we work on next?)

gregsdennis opened this issue · 3 comments

gregsdennis commented

@jdesrosiers and I had some brief "in passing" discussion somewhere about how the specification flow could be improved.

  • definitions could be consolidated
  • some related sections could be brought together
  • etc.

We currently have a plan of things to do, and there are a lot of smaller things that could be done once #1510 (vocab extraction) goes through.

I'm less interested at this time about exactly what those edits entail, but more interested in the order in which we work on all of the open issues we already have relative to this big edit.

So how do we want to do this? (How do you want to review it?)

🚀 large edit up front, then the smaller things
🎉 smaller issues up front, then the big edit
😕 some smaller issues, the big edit in the middle, then finish with more smaller issues
😄 just do the smaller things to get the spec out, and do the big edit for the next release

I think 🎉 and 😕 will end up being the same thing. If we do all of the smaller things that we currently have, we'll inevitably have more smaller things crop up while we're doing the big edit.

I'm okay with all of these options, but I want to hear from the rest of the team. Emoji voting enabled.

jviotti commented

I vote for "smaller issues up front, then the big edit" for the following reasons:

  • There might be a lot of little ones that are easy and we can just get them out of the way fast, forget about them, and then have less cognitive overhead to focus on the remaining/complex ones
  • Option 4 sounds appealing, but I don't think there is any external pressure or deadlines for getting a new version of the spec out. We can probably take as much time as we need to polish it?
jviotti commented

Given the current change of options, Option 4 sounds good.

gregsdennis commented

Seems like the majority of the team has gone for just waiting until after the next version. That's my leaning as well, but I didn't want to influence the voting. Seems like the safest approach. I'll remove this from the stable release milestone.