Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
JavaScript MDN documentation hierarchy change proposal
41 views
Skip to first unread message
David Bruant
Oct 10, 2012, 5:57:41 AM10/10/12
to dev-mdc
Hi,
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.
# URLs
## Built-ins
### Problem
Let's take the example of Array.isArray :
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/isArray
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.
### Proposal
developer.mozilla.org/{locale}/docs/JavaScript/Reference/Built-ins/Array.isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
There might be better ideas than "Built-ins", I'm all hears.
## Syntax
### Problem
Let's take the example of object literal getter syntax
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/get
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
### Proposal
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/get
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/rest_parameters
# Differenciating constructors and instances
## Problem
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_Objects/Array
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.
Thanks,
David
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.
# URLs
## Built-ins
### Problem
Let's take the example of Array.isArray :
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/isArray
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.
### Proposal
developer.mozilla.org/{locale}/docs/JavaScript/Reference/Built-ins/Array.isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
There might be better ideas than "Built-ins", I'm all hears.
## Syntax
### Problem
Let's take the example of object literal getter syntax
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/get
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
### Proposal
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/get
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/rest_parameters
# Differenciating constructors and instances
## Problem
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_Objects/Array
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.
Thanks,
David
Colby Russell
Oct 10, 2012, 9:28:20 PM10/10/12
to
On 10/10/2012 04:57 AM, David Bruant wrote:
> 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.
> 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.
<https://developer.mozilla.org/en-US/docs/Core_JavaScript_1.5_Reference_reorg>
<http://web.archive.org/web/20060206115241/http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference/reorg>
> Let's take the example of Array.isArray :
> https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/isArray
>
> 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.
have us put things this way (if Array.isArray had existed when that page
was created).
> ### Proposal
>
> developer.mozilla.org/{locale}/docs/JavaScript/Reference/Built-ins/Array.isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
>
> There might be better ideas than "Built-ins", I'm all hears.
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].
1. http://developer.mozilla.org/JavaScript/Reference/Array
2. http://developer.mozilla.org/JavaScript/Reference/Array.prototype
3. http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf
> ## Syntax
>
> ### Problem
>
> Let's take the example of object literal getter syntax
> https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/get
>
> 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".
> ### Proposal
>
> https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/get
> https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/rest_parameters
"proper". Lose the whole thing altogether and be done with it.
Wikipedia is instructive.
* Make <http://developer.mozilla.org/JavaScript/Reference/get>, and
* Make <http://developer.mozilla.org/JavaScript/Reference/...> a
disambiguation page linking to
<http://developer.mozilla.org/JavaScript/Reference/..._(rest_parameters)> and
<http://developer.mozilla.org/JavaScript/Reference/..._(spread)>, with a
blurb about how they're mirror twins.
> # 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
>
> 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.
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.
See
<https://groups.google.com/d/topic/mozilla.dev.mdc/l9Tmt22nQwA/discussion>
or search for the topic "Core JavaScript Reference not so useful
anymore" in this group.
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.
--
Colby Russell
David Bruant
Oct 11, 2012, 6:20:32 AM10/11/12
to Colby Russell, dev...@lists.mozilla.org
Before anything else, thanks for all the history digging. I wasn't there at
the time so it's good to know
2012/10/11 Colby Russell <seven...@gmail.com>
> On 10/10/2012 04:57 AM, David Bruant wrote:
>
>> ### Proposal
>>
>> developer.mozilla.org/{locale}**/docs/JavaScript/Reference/**
>> Built-ins/Array.isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
>> <http:/**/developer.mozilla.org/%**7Blocale%7D/docs/JavaScript/**
>> Reference/Built-ins/Array.**isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
> 2. http://developer.mozilla.org/**JavaScript/Reference/Array.**prototype<http://developer.mozilla.org/JavaScript/Reference/Array.prototype>
> 3. http://developer.mozilla.org/**JavaScript/Reference/Array.**
> prototype.indexOf<http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf>
This looks so good!!
>
> ## Syntax
>>
>> ### Problem
>>
>> Let's take the example of object literal getter syntax
>> https://developer.mozilla.org/**en-US/docs/JavaScript/**
>> Reference/Operators/get<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/get>
>> Reference/Syntax/get<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/get>
>> https://developer.mozilla.org/**en-US/docs/JavaScript/**
>> Reference/Syntax/rest_**parameters<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/rest_parameters>
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.
Maybe "Built-in" is a bad idea, because http://developer.mozilla.org/**
JavaScript/Reference/Array.**prototype.indexOf<http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf>
looks
nice indeed, but it doesn't hurt to have /Syntax especially since it's hard
to make nice URLs with syntax constructs (like ... or the very generic
"get" as can be seen below)
> Wikipedia is instructive.
>
> * Make <http://developer.mozilla.org/**JavaScript/Reference/get<http://developer.mozilla.org/JavaScript/Reference/get>>,
> and
>
> * Make <http://developer.mozilla.org/**JavaScript/Reference/..<http://developer.mozilla.org/JavaScript/Reference/..>.>
> a disambiguation page linking to <http://developer.mozilla.org/**
> JavaScript/Reference/..._(**rest_parameters)<http://developer.mozilla.org/JavaScript/Reference/..._(rest_parameters)>>
> and <http://developer.mozilla.org/**JavaScript/Reference/..._(**spread)<http://developer.mozilla.org/JavaScript/Reference/..._(spread)>>,
>
>
> # 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.
>
> See <https://groups.google.com/d/**topic/mozilla.dev.mdc/**
> l9Tmt22nQwA/discussion<https://groups.google.com/d/topic/mozilla.dev.mdc/l9Tmt22nQwA/discussion>>
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.
It's coming very soon, my friend ;-)
(meta bug) https://bugzilla.mozilla.org/show_bug.cgi?id=764431
http://www.bitstampede.com/2012/10/10/kuma-update-october-10-2012/
I only started to think about a reorg because I knew the support for that
was coming soon :-)
David
the time so it's good to know
2012/10/11 Colby Russell <seven...@gmail.com>
> On 10/10/2012 04:57 AM, David Bruant wrote:
>
>>
>> developer.mozilla.org/{locale}**/docs/JavaScript/Reference/**
>> Built-ins/Array.isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
>> <http:/**/developer.mozilla.org/%**7Blocale%7D/docs/JavaScript/**
>> Reference/Built-ins/Array.**isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
>> >
>>
>>
>> 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].
>
> 1. http://developer.mozilla.org/**JavaScript/Reference/Array<http://developer.mozilla.org/JavaScript/Reference/Array>
>>
>>
>> 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].
>
> 2. http://developer.mozilla.org/**JavaScript/Reference/Array.**prototype<http://developer.mozilla.org/JavaScript/Reference/Array.prototype>
> 3. http://developer.mozilla.org/**JavaScript/Reference/Array.**
> prototype.indexOf<http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf>
This looks so good!!
>
> ## Syntax
>>
>> ### Problem
>>
>> Let's take the example of object literal getter syntax
>> Reference/Operators/get<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/get>
>>
>> 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".
>>
>
> Yup.
>
> ### Proposal
>>
>> https://developer.mozilla.org/**en-US/docs/JavaScript/**
>> 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".
>>
>
> Yup.
>
> ### Proposal
>>
>> Reference/Syntax/get<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/get>
>> https://developer.mozilla.org/**en-US/docs/JavaScript/**
>> Reference/Syntax/rest_**parameters<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/rest_parameters>
>>
>
> 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
>
> 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 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.
Maybe "Built-in" is a bad idea, because http://developer.mozilla.org/**
JavaScript/Reference/Array.**prototype.indexOf<http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf>
looks
nice indeed, but it doesn't hurt to have /Syntax especially since it's hard
to make nice URLs with syntax constructs (like ... or the very generic
"get" as can be seen below)
> Wikipedia is instructive.
>
> * Make <http://developer.mozilla.org/**JavaScript/Reference/get<http://developer.mozilla.org/JavaScript/Reference/get>>,
> and
>
> * Make <http://developer.mozilla.org/**JavaScript/Reference/..<http://developer.mozilla.org/JavaScript/Reference/..>.>
> a disambiguation page linking to <http://developer.mozilla.org/**
> JavaScript/Reference/..._(**rest_parameters)<http://developer.mozilla.org/JavaScript/Reference/..._(rest_parameters)>>
> and <http://developer.mozilla.org/**JavaScript/Reference/..._(**spread)<http://developer.mozilla.org/JavaScript/Reference/..._(spread)>>,
> with a blurb about how they're mirror twins.
I'm not sure about "..." and disambiguiation, but that's an idea.
>
>
> # 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.
>
> l9Tmt22nQwA/discussion<https://groups.google.com/d/topic/mozilla.dev.mdc/l9Tmt22nQwA/discussion>>
> or search for the topic "Core JavaScript Reference not so useful anymore"
> in this group.
>
> 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
> in this group.
>
> 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.
>
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[...]")
>
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.
(meta bug) https://bugzilla.mozilla.org/show_bug.cgi?id=764431
http://www.bitstampede.com/2012/10/10/kuma-update-october-10-2012/
I only started to think about a reorg because I knew the support for that
was coming soon :-)
David
Jean-Yves Perrier
Oct 11, 2012, 10:09:46 AM10/11/12
to dev...@lists.mozilla.org
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
On 11/10/2012 12:20, David Bruant wrote:
> Before anything else, thanks for all the history digging. I wasn't there at
> the time so it's good to know
>
> 2012/10/11 Colby Russell <seven...@gmail.com>
>
>>> Reference/Operators/get<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/get>
>>
>> * Make <http://developer.mozilla.org/**JavaScript/Reference/get<http://developer.mozilla.org/JavaScript/Reference/get>>,
>> and
>>
>> l9Tmt22nQwA/discussion<https://groups.google.com/d/topic/mozilla.dev.mdc/l9Tmt22nQwA/discussion>>
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
>
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
On 11/10/2012 12:20, David Bruant wrote:
> Before anything else, thanks for all the history digging. I wasn't there at
> the time so it's good to know
>
> 2012/10/11 Colby Russell <seven...@gmail.com>
>
>> On 10/10/2012 04:57 AM, David Bruant wrote:
>>
>>
>>> ### Proposal
>>>
>>> developer.mozilla.org/{locale}**/docs/JavaScript/Reference/**
>>> Built-ins/Array.isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
>>> <http:/**/developer.mozilla.org/%**7Blocale%7D/docs/JavaScript/**
>>> Reference/Built-ins/Array.**isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
>>>
>>> developer.mozilla.org/{locale}**/docs/JavaScript/Reference/**
>>> Built-ins/Array.isArray<http://developer.mozilla.org/%7Blocale%7D/docs/JavaScript/Reference/Built-ins/Array.isArray>
>>> <http:/**/developer.mozilla.org/%**7Blocale%7D/docs/JavaScript/**
>>>
>>> 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].
>>
>>> 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].
>>
>> 1. http://developer.mozilla.org/**JavaScript/Reference/Array<http://developer.mozilla.org/JavaScript/Reference/Array>
>> 2. http://developer.mozilla.org/**JavaScript/Reference/Array.**prototype<http://developer.mozilla.org/JavaScript/Reference/Array.prototype>
>> 3. http://developer.mozilla.org/**JavaScript/Reference/Array.**
>> prototype.indexOf<http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf>
> This looks so good!!
>
>
>> 2. http://developer.mozilla.org/**JavaScript/Reference/Array.**prototype<http://developer.mozilla.org/JavaScript/Reference/Array.prototype>
>> 3. http://developer.mozilla.org/**JavaScript/Reference/Array.**
>> prototype.indexOf<http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf>
> This looks so good!!
>
>
>> ## Syntax
>>> ### Problem
>>>
>>> Let's take the example of object literal getter syntax
>>> https://developer.mozilla.org/**en-US/docs/JavaScript/**
>>> ### Problem
>>>
>>> Let's take the example of object literal getter syntax
>>> Reference/Operators/get<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/get>
>>>
>>> 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".
>>>
>> Yup.
>
>> ### Proposal
>>> 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".
>>>
>> Yup.
>
>> ### Proposal
>>> https://developer.mozilla.org/**en-US/docs/JavaScript/**
>>> Reference/Syntax/get<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/get>
>>> https://developer.mozilla.org/**en-US/docs/JavaScript/**
>>> Reference/Syntax/rest_**parameters<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/rest_parameters>
>>> Reference/Syntax/get<https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Syntax/get>
>>> https://developer.mozilla.org/**en-US/docs/JavaScript/**
>>>
>> 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.
>>
>> 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.
>
> Maybe "Built-in" is a bad idea, because http://developer.mozilla.org/**
> JavaScript/Reference/Array.**prototype.indexOf<http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf>
> looks
> nice indeed, but it doesn't hurt to have /Syntax especially since it's hard
> to make nice URLs with syntax constructs (like ... or the very generic
> "get" as can be seen below)
>
>
>
>> Wikipedia is instructive.
> 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.
>
> Maybe "Built-in" is a bad idea, because http://developer.mozilla.org/**
> JavaScript/Reference/Array.**prototype.indexOf<http://developer.mozilla.org/JavaScript/Reference/Array.prototype.indexOf>
> looks
> nice indeed, but it doesn't hurt to have /Syntax especially since it's hard
> to make nice URLs with syntax constructs (like ... or the very generic
> "get" as can be seen below)
>
>
>
>>
>> * Make <http://developer.mozilla.org/**JavaScript/Reference/get<http://developer.mozilla.org/JavaScript/Reference/get>>,
>> and
>>
>> * Make <http://developer.mozilla.org/**JavaScript/Reference/..<http://developer.mozilla.org/JavaScript/Reference/..>.>
>> a disambiguation page linking to <http://developer.mozilla.org/**
>> JavaScript/Reference/..._(**rest_parameters)<http://developer.mozilla.org/JavaScript/Reference/..._(rest_parameters)>>
>> and <http://developer.mozilla.org/**JavaScript/Reference/..._(**spread)<http://developer.mozilla.org/JavaScript/Reference/..._(spread)>>,
>> a disambiguation page linking to <http://developer.mozilla.org/**
>> JavaScript/Reference/..._(**rest_parameters)<http://developer.mozilla.org/JavaScript/Reference/..._(rest_parameters)>>
>> with a blurb about how they're mirror twins.
> I'm not sure about "..." and disambiguiation, but that's an idea.
>
>
>>
>
>
>>
>> # 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 :-)
>> ...
>>
>> ## 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.
>>
>> See <https://groups.google.com/d/**topic/mozilla.dev.mdc/**
>
>> You'll have to use archive.org to have a look, because it doesn't look
>> like Kuma handles it well at all.
>>
>> l9Tmt22nQwA/discussion<https://groups.google.com/d/topic/mozilla.dev.mdc/l9Tmt22nQwA/discussion>>
>> or search for the topic "Core JavaScript Reference not so useful anymore"
>> in this group.
>>
>> 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.
>>
>> in this group.
>>
>> 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.
>
>
> 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[...]")
>>
>> 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.
>
>
>
> 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.
>> though. It's a matter of the server software not supporting this stuff.
> It's coming very soon, my friend ;-)
> (meta bug) https://bugzilla.mozilla.org/show_bug.cgi?id=764431
> http://www.bitstampede.com/2012/10/10/kuma-update-october-10-2012/
>
> I only started to think about a reorg because I knew the support for that
> was coming soon :-)
>
> David
> _______________________________________________
> (meta bug) https://bugzilla.mozilla.org/show_bug.cgi?id=764431
> http://www.bitstampede.com/2012/10/10/kuma-update-october-10-2012/
>
> I only started to think about a reorg because I knew the support for that
> was coming soon :-)
>
> David
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
>
David Bruant
Oct 11, 2012, 10:18:22 AM10/11/12
to Jean-Yves Perrier, dev...@lists.mozilla.org, dev...@lists.mozilla.org
[cc'ing dev-mdn]
2012/10/11 Jean-Yves Perrier <jper...@mozilla.com>
> 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
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
David
2012/10/11 Jean-Yves Perrier <jper...@mozilla.com>
> 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 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
>
> 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)
>
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).
>
"Array.isArray" in the URL
David
l.m.orchard
Oct 11, 2012, 10:55:51 AM10/11/12
to David Bruant, dev...@lists.mozilla.org, dev...@lists.mozilla.org, Jean-Yves Perrier
----- Original Message -----
> From: "David Bruant" <brua...@gmail.com>
> Subject: Re: JavaScript MDN documentation hierarchy change proposal
>
> [cc'ing dev-mdn]
>
> 2012/10/11 Jean-Yves Perrier <jper...@mozilla.com>
...
> From: "David Bruant" <brua...@gmail.com>
> Subject: Re: JavaScript MDN documentation hierarchy change proposal
>
> [cc'ing dev-mdn]
>
> 2012/10/11 Jean-Yves Perrier <jper...@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.
...
> > 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.
> 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.
I don't think separating the URL from the topic hierarchy structure is something that would be easy or happen quickly.
--
lorc...@mozilla.com
{web,mad,computer} scientist
Sheppy
Oct 17, 2012, 4:27:11 PM10/17/12
to David Bruant, dev...@lists.mozilla.org, Jean-Yves Perrier
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).
Eric Shepherd
Developer Documentation Lead
Mozilla
http://www.bitstampede.com/
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).
Eric Shepherd
Developer Documentation Lead
Mozilla
http://www.bitstampede.com/
Sheppy
Oct 17, 2012, 4:27:11 PM10/17/12
to mozilla...@googlegroups.com, dev...@lists.mozilla.org, Jean-Yves Perrier, David Bruant
0 new messages