API structure conventions: dictionaries

[Elchi3]

MDN doesn't consistently document dictionaries.
This came up within the BCD context previously as well in mdn/browser-compat-data#7287
This issue is about making a call on MDN documentation structures.

---

"Web IDL dictionaries are a spec author convenience for describing plain JavaScript objects. Dictionaries are typically used as arguments, often for init dictionaries for constructors, and sometimes as the return types for methods." says @foolip.

On MDN you can find dictionaries documented in at least three forms:

1. Dictionaries are documented like API interfaces.
   • Example: https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialCreationOptions
   • Sub pages for every property
2. Dictionaries are documented on a single dedicated page
   • Example: https://developer.mozilla.org/en-US/docs/Web/API/RsaOaepParams
   • No sub pages for every property
3. Dictionaries are documented inline on constructor/method pages
   • Example: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext (contextAttributes)
   • Information appears within context

What is best?

I've been documenting things inline (like in the canvas case), so I'm a fan of option 3.

@sideshowbarker summarizes well what I'm thinking, too (mdn/browser-compat-data#7287 (comment))

In fact I think it could reasonably said that having dictionaries documented separately in MDN creates an unnecessary level of indirection that’s an inconvenience for web developers — because web developers only care, for example, what parameters a particular method actually has, and they want to see that information at point of use, rather than needing to navigate over to yet another separate MDN article to find the information they need.

---

Thoughts?

[dontcallmedom]

I prefer (3) although I suspect there are cases where (2) is more appropriate, e.g.:

• dictionaries that are re-used in multiple APIs, or inherited from multiple other dictionaries
• dictionaries whose inline documentation would make the page very long / hard to grok

In other words, I think (3) makes the best default approach, but we should probably leave room for (2) when warranted; I think (1) is an overkill in general.

Another thought: I don't think it's useful for MDN to be talking about "dictionaries" and/or to name them, as in:

This is an EventInit dictionary
https://developer.mozilla.org/en-US/docs/Web/API/Event/Event

From a JS developer perspective, dictionaries aren't a thing; and the name given to a dictionary is not something they don't particularly need to be aware of. I don't know if this is a consideration for this issue, or one that ought to be discussed separately.

[Ryuno-Ki]

From a JS developer perspective, dictionaries aren't a thing;

Unless they have former Python knowledge, where a dict corresponds roughly to a JS object literal ;-)
Perhaps we should make clear, that it is not a distinct type like Map or Object.

I have no strong feelings about either option (since I haven't get my hands dirty with making changes on MDN yet).

[jpmedley]

I also prefer 3, granting that it, like #1940 also argues for a reuse or inclusion mechanism. The poster child for this is the Payment APIs. The data used in a transaction has similar structures in different places. To even get a handle on this when documenting it, I printed all the structures, taped them into one sheet of paper, and drew lines to indicate, which properties pointed to which child structures.

This is an extreme example, but it illustrates a principle that I've always believed about technical writing; my job is to resolve confusion so that developers don't need to.

[foolip]

I don't think my opinion should count for much when it comes to what's best for web developer documentation, but @dontcallmedom's comments in mdn/content#1948 (comment) match my own views.

Because dictionaries are just plain objects in JS their names are invisible, but I'm not sure how to describe common shapes of objects with giving them a name. I would also say that the fact that Web IDL dictionaries are just JS objects doesn't necessarily mean the terminology should be avoided on MDN. Compare it to Web IDL interfaces are function objects in JS and could be described as objects (like Map) but that's not current practice.

[jpmedley]

Because dictionaries are just plain objects in JS their names are invisible

And sometimes other names or actually visible within script or its reference. I don't know how many function have an argument simply named options defined as a dictionary with a name like WidgetParameters or some such thing.

[Ryuno-Ki]

I don't know how many function have an argument simply named options defined as a dictionary with a name like WidgetParameters or some such thing.

In ye olden days, this was called the „Configuration Object Pattern” and used to „trim down” the number of arguments (and define sane defaults etc).

[chrisdavidmills]

I would also prefer 3, with an option for 2 if the dictionary definition gets particularly long and troublesome. In fact, a useful half-way-house approach might be to provide a really quick description of each property inside the object, and then point to a separate page for the full information if you need it, e.g.

---

Parameters

options

A dictionary object containing the following properties:

• x: blah blah blah
• y: blah blah blah
• z: blah blah blah

If you need more detailed information about these properties, see the BlahDictionaryObject page.

---

The above approach is basically what I've always told MDN contributors to do anyway. Always having a separate page for every dictionary is just overkill.

In terms of naming dictionaries, I agree with @dontcallmedom ; we should avoid it as much as much as possible. The only places we should mention an actual dictionary name are in the link to the separate object page, if there is one.

In terms of what to generically refer to the dictionary object as, I've used "dictionary object" above, but we can probably even just say "object". Do we even need to mention the word "dictionary" at all?

[hamishwillee]

This has come up again in mdn/content#5975 (comment) where there is going to be a removal of 4 dictionaries from BCD. I have back linked to here, but we might want to have a summary somewhere of the result of this discussion.

My understanding of the above is that we're using dictionaries for the same reason spec authors do - to avoid having to duplicate common ideas lots of times. The consensus seems to be that if the dictionary can reasonably be included inline then it should be - we are happy to live with a certain amount of duplication and reuse to simplify things for developers (not introduce names for things that have no relevance to API users). We're a bit stalled on what to do when a dictionary object is reused a lot of times, but since we're not running a project to "fix" this right now, that hasn't caused a problem. Is that about right?

My only thought on top of this is that the name of a dictionary isn't relevant to end users until it is - when they end up in the spec. So I don't think I have a problem having text like "this object is referred to as XXX in the spec".

[jpmedley]

It sounds right to me.

[Rumyra]

I think this is answered: Option 3, unless there is a case for a separate page as per the above comments 👍

I do have one query - how do we know if a dictionary is reused elsewhere? I'm hoping it's in IDL but I'm not sure I've come across a case yet.

I've added a personal todo to include this when I go through contributor docs.

[hamishwillee]

how do we know if a dictionary is reused elsewhere? I'm hoping it's in IDL but I'm not sure I've come across a case yet.

What do you mean? In the MDN docs before cleanup it is obvious from the fact that the dictionary is documented separately. After cleaning up the docs though you don't know there was ever a reused dictionary (and the point then is it does not matter, because the dictionary was only ever used as a convenience for docs and spec authors).

[foolip]

@Rumyra one can figure this out with a checkout of https://github.com/w3c/webref/tree/master/ed/idl, searching that repo/directory for the dictionary name.

[Rumyra]

Yes this is irrelevant to authors @hamishwillee it was merely something I was thinking about :)

Thanks @foolip that's a great tip 👍

[pepelsbey]

Closing as answered/settled.