Documenting dictionaries

[Eric Shepherd]

I know it's lately been common to document dictionaries inline in the
interface page for the API that uses them, but...

1. I don't think this is a good idea. It makes the material hard to
find and to link to. It also makes articles a little too cluttered.
2. It makes things messy when a dictionary needs to be referenced from
multiple documents.

I would prefer to document them as if they were interfaces, except
tagged as Dictionary instead of Interface. We can then tweak the APIRef
and other macros that matter to recognize them. Or we could just use
"Interface" and "Dictionary" which would let them sort either way but
that seems pretty wrong to me. :)

I am currently using this approach for new material in the WebRTC
reference because it makes the content easier to follow. Are there any
shrieking objections? If so, why?

Anyway, the tagging issue is the main thing here: should I update the
APIRef macro to also look for dictionaries, and if so, should they be
listed separately or bundled in with the interfaces? I see advantages to
both options.

--

Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: https://www.bitstampede.com/
Twitter: http://twitter.com/sheppy
Doodle: http://doodle.com/the.sheppy

[Chris Mills]

I’ve had a bit of think about this, and looked back at how I handled dictionaries when I was doing a load of API docs. I think having them on a separate page makes sense for sure if you need to reference them from multiple documents.

BUT …

I think we need to weigh up “absolute correctness” versus ease of use of the documentation.

For example, take my doc on the Fetch API Request interface constructor:

https://developer.mozilla.org/en-US/docs/Web/API/Request/Request

This lists the optional init object as being an object containing options you may want to pass when creating this object instance. The examples section below it shows an explicit usage example to make it absolutely clear how to use this.

But I don’t mention that it is a RequestInit dictionary, as I don’t think many developers need this level of explicit detail thrown at them. If developers really want to know exactly what type of init object it is, they can go to the spec link (https://fetch.spec.whatwg.org/#dom-request), then look up the RequestInit link in the WebIDL (https://fetch.spec.whatwg.org/#requestinit)

But I don’t think most developers want or need this.

If I did add this level of detail to my Request doc, then I’d have to create another 12 pages of documentation just for this dictionary, and then every time a reader wanted to look up how to write one of these dictionary objects, they’d have to do an extra navigation to the dictionary page, and then an extra navigation to each of the object property pages.

Which seems like a step too far to me, just to look up details on a constructor parameter.


Having an extra page for the dictionary object makes perfect sense when it is used in multiple places — repeating that information multiple times would make no sense. But in cases where we have to do this, should we just make dictionary definitions single pages containing all the property info?

Have I got a point here, or am I just being a slacker? I’m not sure ;-)

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status

[Eric Shepherd]

I suppose we could simply have the summary style page without the
subpages for these, although my inherent dislike of inconsistency is
shrieking in pain as I write that. I would probably go ahead and write
the subpages (personally) but make sure the summary page is detailed
enough that you don't typically need to click through in most cases,
perhaps.

------------------------------------------------------------------------
*From:* Chris Mills
*Sent:* Tuesday, Apr 26, 2016 3:51:57 AM EDT
*To:* Eric Shepherd
*Cc:* dev...@lists.mozilla.org
*Subject:* [dev-mdc] Documenting dictionaries

> Having an extra page for the dictionary object makes perfect sense when it is used in multiple places — repeating that information multiple times would make no sense. But in cases where we have to do this, should we just make dictionary definitions single pages containing all the property info?

[Chris Mills]

Ok, I think that’s reasonable — there is a chance that someone might want to view or link through to a page that just details one init object property. But most people won’t. This serves both purposes without any extra pain for either group.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> On 26 Apr 2016, at 17:39, Eric Shepherd <eshe...@mozilla.com> wrote:
>
> I suppose we could simply have the summary style page without the subpages for these, although my inherent dislike of inconsistency is shrieking in pain as I write that. I would probably go ahead and write the subpages (personally) but make sure the summary page is detailed enough that you don't typically need to click through in most cases, perhaps.
>

> From: Chris Mills
> Sent: Tuesday, Apr 26, 2016 3:51:57 AM EDT
> To: Eric Shepherd
> Cc: dev...@lists.mozilla.org
> Subject: [dev-mdc] Documenting dictionaries
>
>> Having an extra page for the dictionary object makes perfect sense when it is used in multiple places — repeating that information multiple times would make no sense. But in cases where we have to do this, should we just make dictionary definitions single pages containing all the property info?
>
> --
>
> Eric Shepherd
> Senior Technical Writer
> Mozilla Developer Network

[William Bamberg]

If this is about what I think it is about, then... the WebExtensions docs
have things they call "Types", which are like this. When an API makes use
of a data structure across a few different functions/events, then we have a
separate page documenting that structure in one place, and refer to it from
the other places.

Example: a lot of the bookmark APIs (
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/bookmarks)
use a thing called a BookmarkTreeNode, which is a thing (either a bookmark
or a folder) in the bookmarks hierarchy:
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/Bookmarks/BookmarkTreeNode
.

If the data structure is only used in one place, I tend to document it
inline in the place where it's used.

[Eric Shepherd]

The one thing is... in GroupData, do I add these under Interfaces?
They're not interfaces... but they're very similar from a documentation
perspective, and we don't at this time have a category for dictionaries.
I think we should add one, or one for data types in general even, which
could then contain dictionaries and any other type-like constructs.

------------------------------------------------------------------------
*From:* Chris Mills

*Sent:* Tuesday, Apr 26, 2016 12:41:40 PM EDT

*To:* Eric Shepherd
*Cc:* dev...@lists.mozilla.org
*Subject:* [dev-mdc] Documenting dictionaries

> Ok, I think that’s reasonable — there is a chance that someone might want to view or link through to a page that just details one init object property. But most people won’t. This serves both purposes without any extra pain for either group.

--

Eric Shepherd
Senior Technical Writer

Mozilla Developer Network <https://developer.mozilla.org/>

[Chris Mills]

I’m not convinced we need to list them in GroupData … they are pages that exist to supplement/enhance method/constructor pages, not particularly useful pages in their own right.

If someone wanted to find out what values a particular init object parameter takes, they’d probably start by finding the method that takes it as a parameter, not looking for the name of the parameter/dictionary.

I don’t think that many web developers know what enums and dictionaries are, either. They seem to me like spec objects.

Feel free to disagree/slap me, of course ;-)

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> On 6 May 2016, at 22:12, Eric Shepherd <eshe...@mozilla.com> wrote:
>
> The one thing is... in GroupData, do I add these under Interfaces? They're not interfaces... but they're very similar from a documentation perspective, and we don't at this time have a category for dictionaries. I think we should add one, or one for data types in general even, which could then contain dictionaries and any other type-like constructs.
>

> From: Chris Mills
> Sent: Tuesday, Apr 26, 2016 12:41:40 PM EDT
> To: Eric Shepherd
> Cc: dev...@lists.mozilla.org

> Subject: [dev-mdc] Documenting dictionaries
>
>> Ok, I think that’s reasonable — there is a chance that someone might want to view or link through to a page that just details one init object property. But most people won’t. This serves both purposes without any extra pain for either group.
>
> --
>
> Eric Shepherd
> Senior Technical Writer
> Mozilla Developer Network