Ordering of features and APIs

[snoack]

Currently, APIs and their sub-features are listed in arbitrary order. I think we should put them in the order they have been added to Firefox (then Chrome). There is also the suggestion to sort them alphabetically.

I prefer implementation order, since the story reads more clearly, having essential features that are widely supported listed first, followed by newer features. Also this seems consistent with the vast majority of existing documentation on MDN.

@wbamberg @Elchi3

[jpmedley]

Can you provide more context please? Which macro are you talking about?

[snoack]

Assuming you are talking about rendering the data on MDN, currently sub-features appear in the order they occur in the raw data (the JSON files in this repository). As far as I'm concerned, this is fine, but I'd rather ensure the raw data to have a sane and consistent structure in the first place. Regardless of that, I think implementation order is more useful than alphabetic (or arbitrary) order, for reasons outlined above.

[wbamberg]

Oh, here's the corresponding issue for the macros: mdn/kumascript#193.

[wbamberg]

So first, the order of features and subfeatures in the JSON can be separated from the order of features and subfeatures in compat tables on MDN. The macros that build compat tables for MDN can (and should) reorder data to follow their policy (and other possible consumers might want to have a different policy).

But I think it makes sense to have some kind of defined order for both the raw data and the MDN compat tables.

I like alphabetizing, for two reasons really:

• it's the simplest policy: it's a really easy rule for readers and contributors to understand. Ordering by implementation order (by Firefox, then Chrome, then...?) is more complicated to grasp.

• choosing a browser to order by (Firefox) seems to be against a policy of browser-neutrality. Alphabetizing is neutral.

I do take your point that ordering by implementation version can help tell the story of how subfeatures were added. There are lots of features where this doesn't apply though, and in those cases, ordering by implementation version just seems arbitrary.

[jpmedley]

I agree with everything he says. I think it's best summarized this way: *we can't assume all browsers will implement in the same order.* Joe Medley | Technical Writer, Chrome DevRel | jmedley@google.com | 816-678-7195 *If an API's not documented it doesn't exist.*

…

On Thu, Jun 22, 2017 at 11:34 AM, wbamberg ***@***.***> wrote: So first, the order of features and subfeatures in the JSON can be separated from the order of features and subfeatures in compat tables on MDN. The macros that build compat tables for MDN can (and should) reorder data to follow their own policy (and other possible consumers might want to have a different policy). But I think it makes sense to have some kind of defined order for both the raw data and the MDN compat tables. I like alphabetizing, for two reasons really: - it's the simplest policy: it's a really easy rule for readers and contributors to understand. Ordering by implementation order (by Firefox, then Chrome, then...?) is more complicated to grasp. - choosing a browser to order by (Firefox) seems to be against a policy of browser-neutrality. Alphabetizing is neutral. I do take your point that ordering by implementation version can help tell the story of how subfeatures were added. There are lots of features where this doesn't apply though, and in those cases, ordering by implementation version just seems arbitrary. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#264 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH0viz5yZQm4CV6zoq_7axKojFwbgi5Xks5sGrOqgaJpZM4N_JDH> .

[SebastianZ]

I totally agree with @wbamberg. Let's just keep an alphabetical order to be implementer neutral and make the order consistent.

Displaying the data is a totally different topic.

Sebastian

[wbamberg]

It seems like keeping the order alphabetical is the consensus decision. But let's keep this issue open until we have it enforced in the schema or some other validation method.