GroupData and macro updates

MDN
#1

I’m working on implementing support for the new dictionaries, types, and callbacks arrays on entries in GroupData.json. I’ve got some ideas and I’d like to get some other opinions on them as I work on macro changes.

Right now, I’m working on updates to APIRef. What I’m doing is adding an optional second parameter which is a JSON object, options, which lets you specify which items to include in the sidebar. What I’m wondering is a bit about both structure and a couple of ideas on other capabilities. The options I’m looking at are:

  • includeDictionaries: Should the API’s dictionaries be listed? This could just be a binary true or false, or it could be something a little more flexible, like a string that takes values like "yes" (include dictionaries), "no" (don’t include dictionaries), or "important" (include dictionaries which have a tag Important on them). That would give us all kinds of flexibility, such as being able to include dictionaries that are used from multiple interfaces but not the lesser ones.
  • includeTypes: Same as above, but for typedefs and enumerated types.
  • includeCallbacks: Same as above, but for callback types.

Question 1: Any opinions on the options parameter as described above?

As for the default option configuration: right now, I’m defaulting to including dictionaries and types but not callbacks, but that can be changed easily enough. What I’m inclined to do is to implement the string form for options and default to "important" for all three groups.

Question 2: Does the description of what I’m thinking of doing with the defaults make sense to you?

Since APIRef is just listing “Related pages”, there’s no need to categorize; everything just goes into one long list. Other macros may sort things into groups; we’ll get to that in upcoming posts as I get to work on those macros.

Question 3: Any other thoughts on this?

I feel pretty good about this plan; things are coming along swimmingly. As soon as I get a some other opinions, I can finish things up pretty fast on APIRef.

#2

This looks good to me overall. I take it we’d still list all the dictionaries/typedefs/callbacks in groupdata.json, and then use the apiref() options object to specify whether to show them or not.

I am not sure about this “important” tag. I think it’d be a pain to remember to include this in all relevant wiki pages, and quite subjective/opinion-based. What about including it inside the GroupData somehow, so at least it can be all updated quickly in one place?

Something like

"dictionaries": [
  [ "Blah", "important" ],
  [ "BlahBlah", "important" ],
  [ "NotBlah", "normal" ],
]

The defaults sound OK to me.

#3

Yes, that’s precisely the idea. Put it all into GroupData.json, and let the code decide what to show based on the information provided. That gives added flexibility because, for instance, we might want to leave things out of the sidebar if they’re not particularly interesting, but a developer using our data to implement syntax-aware editing might want to know every single thing in order to establish useful connections among related items in the editor.

That’s a good point. I have been feeling iffy about the “important” tag idea myself, and I think I like the idea of putting that information inside GroupData.json. It will involve slightly larger changes to the macros that will be affected (which would only be those supporting the new classifications for now, since my inclination is to save implementing support for it on interfaces for later). I will experiment a bit with this.

#4

We should also move GroupData and similar into mdn-data (on npm), which is mentioned in the KumaScript Macro Massacre spreadsheet.

#5

Yes, but that should be handled under separate cover from this set of work, I think.

#6

I am not sure about this “important” tag. I think it’d be a pain to remember to include this in all relevant wiki pages, and quite subjective/opinion-based. What about including it inside the GroupData somehow, so at least it can be all updated quickly in one place?

What are the semantics of “important”? If it’s just “I want to include this in the sidebar” then we should probably be more explicit that this is what it means, and not pretend it’s some more generic attribute. So I mean, it would probably be better to have an actual specification for a sidebar that lists the things you want to include in it. Or at least call it “include-in-sidebar” or something. If its semantics are more general than this, what are they and how else should they be used?

I agree that it seems quite subjective. But I’m not sure why it’s better to keep something “subjective/opinion-based” inside GroupData, which in general (as far as I can tell) tries to represent quite objective features of the APIs.

As far as sidebars are concerned: I’d like us to have a user research-based view of what we want sidebars to contain for different technologies, and an implementation of them that avoids the pitfalls of our current macro-based approach.

#7

I thought at first about having a simple Boolean in-sidebar field for each item in GroupData.json to specify whether or not to include it in sidebars, but then It occurred to me that doing so seems very MDN-centric; so I thought up this “importance” system, which would let different sites or tools interpret the value however they wish.

My notion is that MDN would use an importance of "high" to mean “include everywhere this type of item is listed.” A value of "medium" would mean “include in landing page menus and indexes of all API items of this type”, and a value of "low" would mean “include only in indexes of API items of this type.”

So basically, the three tiers would be:

  • "high": Sidebars and the two following tiers’ locations
  • "medium": Landing page menus and the following tier’s locations
  • "low": Quick lists of API terms (such as the one generated by the APIListAlpha macro or places where we currently hand-edit them.

But others might handle these values differently. It seemed to me like a good flexible solution that didn’t impose our opinions on other organizations. However, I do get that the ambiguity is strange, and that this may or may not be the best place for information like this to be kept. I liked the idea because of the flexibility and the immediacy of having this value right with the API’s data.

We could replace this with a simple Boolean, like I originally envisioned it, if we wanted to simplify things. I think we lose some important capabilities here, though. I feel like a three-way selector is needed for this in order to define how to place the items in different scenarios.

Instead, perhaps we replace this with a field that contains, in essence, a bitfield that indicates which places should include the item.

1 Like
#8

It seems to me this effort tries to do two things at once:

  1. Extend the “groupdata” data structure.
  2. Add more things to the sidebar of API docs.

For 1. my steps would be:

  • Agree on a clear data structure and test that structure by a schema.
  • Transfer the data to mdn/data (which I guess is the most fitting home for now)
  • Have KumaScript use mdn/data, so that there is one source of truth (this isn’t the case right now for inheritance data [a dataset that is very related to API data] and it’s the worst).
  • Have an owner that looks after this data, reviews updates to it, etc.

For 2. my steps would be:

  • User research what kind of things we want in the sidebar of API docs and how it’s displayed.
  • Write a clear spec for what exactly we want sidebar navigation to be like based on user research outcomes.
  • Create prototype pages (it’s possible to test this without fiddling with macros at all, we can just put hard-code sidebars on a few pages and iterate).
  • Refactor APIRef to do what the spec we came up with says, use the new data structure from step 1., also write tests for APIRef (used on 10,900 pages, so high risk to make changes to it.)
1 Like
#9

I think GroupData should be migrated to mdn‑data:

#10

Yes, definitely. Any non-browser-specific information should be in mdn/data. That would definitely include the GroupData.json file.

1 Like