I've been thinking about how the JavaScript MDN documentation is organized
and wish to change this organization to be more easily searchable and so
that the documentation hierarchy helps better undertsand how the language
works.
In this message, I'll be explaining problems I see, proposing improvements.
After constructive debates, I'll write another proposal and reach out to
the broader JavaScript community. After another round of feedback, I think
it'll be time to actually make the changes.
Pretty much everything is fine except:
* "Global_Objects". I think very few people search for "global objects
Array". I wish I would say I know what people search for, but I don't.
jean-Yves, do you have generic keywords often used for built-in library
searches?
* "Array/isArray"
There is no reason not to have "Array.isArray" in the URL.
Everything is fine except "Operators". The "get" is not an operator (while
"+" or "!" are). It might be that JavaScript MDN doc grew organically so
people just used "Operators" as a generic (but misleading) term for
"syntax".
However, as new syntax constructs (destructuring, default arguments, for-of
loops...) are added, I think it's time to fix the terminology
As mentioned in an older post, there is an ambiguity when people are
searching for "object" or "array". Are they looking for the Array
constructor or array instances. We might consider take casing into account,
but that doesn't sound like a reliable improvement over what we currently
have.
Currently the content for both the Array constructor and array instances
are in the same page
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_... Likewise for dates and some others.
## Proposal
Have 2 pages, one for the constructor, one for the instances. Each page
contains a disambiguation message like:
"You're looking at the Array constructor page. If you're interested in how
array instances work, there is another page for that" (with link to the
page).
Likewise in the array instances page.
I'm hopeful this distinction will help newcomers to JavaScript understand
better the constructor/instances thing and that constructors and objects
themselves too.
I can make a disambiguation template to be put on top of each page where
it's necessary.
I don't see any other big problem with the JavaScript hierarchy.
Tell me what you think.
> In this message, I'll be explaining problems I see, proposing improvements.
> After constructive debates, I'll write another proposal and reach out to
> the broader JavaScript community. After another round of feedback, I think
> it'll be time to actually make the changes.
There has been a proposal to do these things since 2006.
> Pretty much everything is fine except:
> * "Global_Objects". I think very few people search for "global objects
> Array". I wish I would say I know what people search for, but I don't.
> jean-Yves, do you have generic keywords often used for built-in library
> searches?
> * "Array/isArray"
> There is no reason not to have "Array.isArray" in the URL.
This is truth. You'll notice that the "reorg" link from above would have us put things this way (if Array.isArray had existed when that page was created).
> There might be better ideas than "Built-ins", I'm all hears.
Lose the "Built-ins" part, too. And as long as we're talking about what's ideal, the {locale}/docs/ needs to go away, too. "Built-ins" is nice, but there's no reason for the hierarchical stuff to appear anywhere but on the reference's main index page.
Using indexOf as an example:
"MDN > JavaScript > Reference > Array.prototype.indexOf" should be the breadcrumbs, where the dots can take the place of the standard breadcrumb separators; "Array" links to [1], "prototype" links to [2], and indexOf is the page you're on, located at [3].
> Everything is fine except "Operators". The "get" is not an operator (while
> "+" or "!" are). It might be that JavaScript MDN doc grew organically so
> people just used "Operators" as a generic (but misleading) term for
> "syntax".
> # Differenciating constructors and instances
...
> ## Proposal
> Have 2 pages, one for the constructor, one for the instances. Each page
> contains a disambiguation message like:
> "You're looking at the Array constructor page. If you're interested in how
> array instances work, there is another page for that" (with link to the
> page).
> Likewise in the array instances page.
> I'm hopeful this distinction will help newcomers to JavaScript understand
> better the constructor/instances thing and that constructors and objects
> themselves too.
> I can make a disambiguation template to be put on top of each page where
> it's necessary.
:D
Don't do it, man.
I did *exactly* this in 2008. You'll have to use archive.org to have a look, because it doesn't look like Kuma handles it well at all.
What it comes down to is that, as Shaver said then, when people click through to the "String" page from the Reference index, they want to see the methods to manipulate string instances.
(As an aside: I felt *really* vindicated with ES5, where most of the methods added were on the constructors themselves instead of the prototype. E.g., Object.defineProperty(obj, desc) instead of obj.definePropery(desc). And it's funny today seeing Shaver write, "Script authors don't -- and don't need to -- understand the prototype model, in the large[...]")
***
The issue with the reorganization stuff is the same now as it was then, though. It's a matter of the server software not supporting this stuff.
>> There might be better ideas than "Built-ins", I'm all hears.
> Lose the "Built-ins" part, too. And as long as we're talking about what's
> ideal, the {locale}/docs/ needs to go away, too. "Built-ins" is nice, but
> there's no reason for the hierarchical stuff to appear anywhere but on the
> reference's main index page.
> Using indexOf as an example:
> "MDN > JavaScript > Reference > Array.prototype.indexOf" should be the
> breadcrumbs, where the dots can take the place of the standard breadcrumb
> separators; "Array" links to [1], "prototype" links to [2], and indexOf is
> the page you're on, located at [3].
>> Everything is fine except "Operators". The "get" is not an operator (while
>> "+" or "!" are). It might be that JavaScript MDN doc grew organically so
>> people just used "Operators" as a generic (but misleading) term for
>> "syntax".
> Again, no need to replace a saw horse with a track hurdle just to be
> "proper". Lose the whole thing altogether and be done with it.
It's not that much about being proper or ideal. JavaScript evolves. i think
it's nice if people can easily understand if something new is just syntax
(which is just a convenience, but brings nothing new) against a new
feature, like WeakMap or Proxies which bring a new capability to the
language. The boundary I'm trying to make is between "what you can do with
the language" and "how to express yourself with the available syntax". I
think is a worthwhile distinction to be made, akin to the difference
between ideas (which are abstract) and the "syntax" to express an idea
(which is just a mean differing from language to language). With the rise
of compile-to-JS languages, differenciating the "VM" and the syntax will
become increasingly important I think.
>> Have 2 pages, one for the constructor, one for the instances. Each page
>> contains a disambiguation message like:
>> "You're looking at the Array constructor page. If you're interested in how
>> array instances work, there is another page for that" (with link to the
>> page).
>> Likewise in the array instances page.
>> I'm hopeful this distinction will help newcomers to JavaScript understand
>> better the constructor/instances thing and that constructors and objects
>> themselves too.
>> I can make a disambiguation template to be put on top of each page where
>> it's necessary.
> :D
> Don't do it, man.
> I did *exactly* this in 2008.
Ok, lesson learned :-)
> You'll have to use archive.org to have a look, because it doesn't look
> like Kuma handles it well at all.
> What it comes down to is that, as Shaver said then, when people click
> through to the "String" page from the Reference index, they want to see
> the methods to manipulate string instances.
This is very true. So I guess we need to have both content on the same
page. I wish to find a way to being able to differentiate both on the page
anyway, but it can come later.
> (As an aside: I felt *really* vindicated with ES5, where most of the
> methods added were on the constructors themselves instead of the prototype.
> E.g., Object.defineProperty(obj, desc) instead of obj.definePropery(desc).
> And it's funny today seeing Shaver write, "Script authors don't -- and
> don't need to -- understand the prototype model, in the large[...]")
Things have changed a lot since 2008. The trend is not to "script authors",
but "app developers" with the idea of larger-scale application. I think
it's more relevant today that ever that people understand how JavaScript
works.
> The issue with the reorganization stuff is the same now as it was then,
> though. It's a matter of the server software not supporting this stuff.
I'm all for having shorter URLs (I still have to look in details about JavaScript).
But I do believe we should untie the breadcrumbs and the URL. (As we just untied <title> and <h1>, and partly URL)
We want as short URL as possible (to ease search, better SERP, but also URL guessing), but we want more complex breadcrumbs to ease navigation.
To take examples outside the JavaScript hierarchy:
{locale}/docs/CSS/animation-duration is a nice URL (I skip the {locale}/docs problem, which is a separate one)
But:
CSS > Reference > Animations > animation-duration is a better breadcrumbs for navigation as hovering/clicking on each keyword bring adequate links.
(To have the '.' as a breadcrumb separator, and hence as a link separate is 'a priori' ok too, given that the theme gives enough hint they are clickable)
Regarding JavaScript, I'm not sure to have understood if there is a significant homonym problem or not (I'm a bit lost with prototype method and non-prototype method).
(Note that I don't have filled the bug for separating breadcrumbs and URL hierarchy)
-- Jean-Yves
>>> There might be better ideas than "Built-ins", I'm all hears.
>> Lose the "Built-ins" part, too. And as long as we're talking about what's
>> ideal, the {locale}/docs/ needs to go away, too. "Built-ins" is nice, but
>> there's no reason for the hierarchical stuff to appear anywhere but on the
>> reference's main index page.
>> Using indexOf as an example:
>> "MDN > JavaScript > Reference > Array.prototype.indexOf" should be the
>> breadcrumbs, where the dots can take the place of the standard breadcrumb
>> separators; "Array" links to [1], "prototype" links to [2], and indexOf is
>> the page you're on, located at [3].
>>> Everything is fine except "Operators". The "get" is not an operator (while
>>> "+" or "!" are). It might be that JavaScript MDN doc grew organically so
>>> people just used "Operators" as a generic (but misleading) term for
>>> "syntax".
>> Again, no need to replace a saw horse with a track hurdle just to be
>> "proper". Lose the whole thing altogether and be done with it.
> It's not that much about being proper or ideal. JavaScript evolves. i think
> it's nice if people can easily understand if something new is just syntax
> (which is just a convenience, but brings nothing new) against a new
> feature, like WeakMap or Proxies which bring a new capability to the
> language. The boundary I'm trying to make is between "what you can do with
> the language" and "how to express yourself with the available syntax". I
> think is a worthwhile distinction to be made, akin to the difference
> between ideas (which are abstract) and the "syntax" to express an idea
> (which is just a mean differing from language to language). With the rise
> of compile-to-JS languages, differenciating the "VM" and the syntax will
> become increasingly important I think.
>> # Differenciating constructors and instances
>> ...
>> ## Proposal
>>> Have 2 pages, one for the constructor, one for the instances. Each page
>>> contains a disambiguation message like:
>>> "You're looking at the Array constructor page. If you're interested in how
>>> array instances work, there is another page for that" (with link to the
>>> page).
>>> Likewise in the array instances page.
>>> I'm hopeful this distinction will help newcomers to JavaScript understand
>>> better the constructor/instances thing and that constructors and objects
>>> themselves too.
>>> I can make a disambiguation template to be put on top of each page where
>>> it's necessary.
>> :D
>> Don't do it, man.
>> I did *exactly* this in 2008.
> Ok, lesson learned :-)
>> You'll have to use archive.org to have a look, because it doesn't look
>> like Kuma handles it well at all.
>> What it comes down to is that, as Shaver said then, when people click
>> through to the "String" page from the Reference index, they want to see
>> the methods to manipulate string instances.
> This is very true. So I guess we need to have both content on the same
> page. I wish to find a way to being able to differentiate both on the page
> anyway, but it can come later.
>> (As an aside: I felt *really* vindicated with ES5, where most of the
>> methods added were on the constructors themselves instead of the prototype.
>> E.g., Object.defineProperty(obj, desc) instead of obj.definePropery(desc).
>> And it's funny today seeing Shaver write, "Script authors don't -- and
>> don't need to -- understand the prototype model, in the large[...]")
> Things have changed a lot since 2008. The trend is not to "script authors",
> but "app developers" with the idea of larger-scale application. I think
> it's more relevant today that ever that people understand how JavaScript
> works.
> I'm all for having shorter URLs (I still have to look in details about
> JavaScript).
> But I do believe we should untie the breadcrumbs and the URL. (As we just
> untied <title> and <h1>, and partly URL)
> We want as short URL as possible (to ease search, better SERP, but also
> URL guessing), but we want more complex breadcrumbs to ease navigation.
> To take examples outside the JavaScript hierarchy:
> {locale}/docs/CSS/animation-**duration is a nice URL (I skip the
> {locale}/docs problem, which is a separate one)
> But:
> CSS > Reference > Animations > animation-duration is a better breadcrumbs
> for navigation as hovering/clicking on each keyword bring adequate links.
> (To have the '.' as a breadcrumb separator, and hence as a link separate
> is 'a priori' ok too, given that the theme gives enough hint they are
> clickable)
It seems like it's be a significant change in how URL and breadcrumbs will
be related, because up to now, it was pretty straightforward.
If we want to go down that road, we need to think about it as early as
possible.
> Regarding JavaScript, I'm not sure to have understood if there is a
> significant homonym problem or not (I'm a bit lost with prototype method
> and non-prototype method).
There is none as long as we can write "Array.prototype.concat" vs
"Array.isArray" in the URL
> 2012/10/11 Jean-Yves Perrier <jperr...@mozilla.com>
...
> > But I do believe we should untie the breadcrumbs and the URL. (As
> > we just untied <title> and <h1>, and partly URL)
> > We want as short URL as possible (to ease search, better SERP, but
> > also URL guessing), but we want more complex breadcrumbs to ease
> > navigation.
...
> It seems like it's be a significant change in how URL and breadcrumbs
> will be related, because up to now, it was pretty straightforward.
> If we want to go down that road, we need to think about it as early
> as possible.
Breadcrumbs and URL paths are very tightly bound in Kuma. And, as development progresses, new features have only been making that relationship more ingrained. We've just done a ton of recent work with page moving that relies on that relationship.
I don't think separating the URL from the topic hierarchy structure is something that would be easy or happen quickly.
I personally prefer URLs and breadcrumbs to be strongly bound together and to match. I'm fine with moving content around, however, to adjust the breadcrumb chain; indeed, a massive site reorg is one of MDN's priorities for the coming months.
I agree with everything I see here about the JS documentation; it does need to be straightened up and it sounds like the proposals here are all reasonable ones (given the constraint of not separating breadcrumbs from URLs).
I personally prefer URLs and breadcrumbs to be strongly bound together and to match. I'm fine with moving content around, however, to adjust the breadcrumb chain; indeed, a massive site reorg is one of MDN's priorities for the coming months.
I agree with everything I see here about the JS documentation; it does need to be straightened up and it sounds like the proposals here are all reasonable ones (given the constraint of not separating breadcrumbs from URLs).
