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 #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?

[sideshowbarker]

I propose we move this to the Discussions tracker.