Core JavaScript Reference not so useful anymore
Axel Hecht
I'm just struggling to find the methods defined on the Number global object.
On
http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Number,
there are tons of links, but no content to methods. Those are hidden in
a subtle little warning, and in random links. In particular, links to
prototype lead to different places. In particular none of the links
beneath the Methods TOC lead anywhere useful,
http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Number#Methods.
What is that supposed to achieve?
Axel
Axel Hecht
moving the links from the global objects pages one click further away,
and a hard to find click.
Axel
Mike Shaver
> For reference, this got changed early this year,
>
> http://developer.mozilla.org/en/docs/index.php?title=Core_JavaScript_1.5_Reference%3AGlobal_Objects%3ANumber&diff=63177&oldid=54414
>
> moving the links from the global objects pages one click further away,
> and a hard to find click.
I agree. I think that while this makes the documentation structure
follow the pure form of the language (as does the ECMA-262 standard),
it's a significant usability regression. Script authors don't -- and
don't need to -- understand the prototype model, in the large, and
virtually everyone who goes to the String page wants to know what they
can do with Strings, not what they can do with the String constructor.
The small text atop the pages is unlikely to remedy it
It looks like SevenSpade has been making these changes, though I
haven't seen discussion on the list of it; maybe elsewhere? Can
someone connect with him to see about reverting these changes, and
looking at other ways to improve the organization of the docs? If we
had JS:String and JS:String_(constructor), with interlinks, I think
that we could have the excellent detail about the structure of the
language that he's added, while making the "obvious" places be where
people are likely to find what they're looking for.
SevenSpade clearly knows quite a bit about JS, and the JS reference
could certainly use the attention, so if we can figure out a more
straightforward way to structure the pages he could do some real good
for us.
Mike
Seven...@gmail.com
I hope to make this post a catch-all for discussion on this issue, and
I guess we should use this thread as a centralized location for all
further discussion on this topic so things aren't so fragmented, which
definitely added to the problems and confusion in this case.
First thing,
On Jan 18, 8:12 pm, "Mike Shaver" <mike.sha...@gmail.com> wrote:
> It looks like SevenSpade has been making these changes, though I
> haven't seen discussion on the list of it; maybe elsewhere? Can
> someone connect with him to see about reverting these changes, and
> looking at other ways to improve the organization of the docs?
As for contacting me, the best way would be by leaving a message on my
MDC talk page. As much as I dislike the implementation of MediaWiki
talk pages, I find the use of the newsgroup to be far more unwieldy
and less productive (or at least used to).
Okay well, the beginning of this issue can be found here: <http://
developer.mozilla.org/en/docs/User_talk:Nickolay#Inherited_properties.
2Fmethods_in_JavaScript_Reference>.
The root of the problem was that the pages documenting the
constructors ambiguously mixed properties of the constructor itself
along with properties of the instances created by that constructor
with no mention of any distinction (actually, I think while making
changes I may have come across one infrequently accessed page that
made a poor and incomplete attempt at doing so). Simply put, /this was
a problem/. See the page documenting Number as it stood before <http://
developer.mozilla.org/en/docs/index.php?
title=Core_JavaScript_1.5_Reference:Global_Objects:Number&oldid=54414>.
Note how there is no mention that MAX_VALUE is a static property while
toFixed et al. should be invoked upon number instances.
To expand upon the second-ish paragraph from what I posted to
Nickolay's talk page,
JavaScript is notorious for being poorly understood, partially due to
its huge accessibility as a language and partially because the
majority of resources available /suck/. The former results in people
pasting poor examples written from the turn of the millennium without
understanding why it works (or doesn't, in many cases)--a school of
thought which I'm not against; not everyone is a computer scientist or
wants to learn about the language as a whole, but just enough for
their stuff to work--while the latter results in those who do want to
learn about JavaScript having few places to look to, and the few
shining stars of information turn out to be not-so-shiny and instead
hidden behind the debris of the aforementioned unsuitable resources.
In my eyes, the JavaScript Reference from DevEdge has been one of the
few attempts at definitive documentation of the language, although it
still had these inaccuracies embedded throughout the structure of the
docs.
Now, the reorganization that has been in planning since ~2005 attempts
to rectify part of this problem by moving everything to the more
appropriately titled /constructor/.prototype./member/ where
applicable, but this doesn't fix the mashed together docs on static
and non-static members.
I opted to throw up a notice as the first thing that appears on the
page (besides breadcrumbs) that closely resembles Wikipedia's
disambiguation headers, which seem to be working for them, in the
clearest language possible.
These changes as a whole were up to now definitely still a work in
progress and there are a few more things that need to be done along
the lines of human-readable descriptions and stuff to be put under
JS:About regarding various issues, like the one Potappo brought up
about pseudo-properties <http://developer.mozilla.org/en/docs/
User_talk:Potappo#Reply_to_Question_for_your_recent_JSRef_edits>.
On Jan 18, 8:12 pm, "Mike Shaver" <mike.sha...@gmail.com> wrote:
> I agree. I think that while this makes the documentation structure
> follow the pure form of the language (as does the ECMA-262 standard),
> it's a significant usability regression. Script authors don't -- and
> don't need to -- understand the prototype model, in the large, and
> virtually everyone who goes to the String page wants to know what they
> can do with Strings, not what they can do with the String constructor.
> The small text atop the pages is unlikely to remedy it.
> . . .
> If we
> had JS:String and JS:String_(constructor), with interlinks, I think
> that we could have the excellent detail about the structure of the
> language that he's added, while making the "obvious" places be where
> people are likely to find what they're looking for.
Regarding the latter portion of this comment of having JS:String and
JS:String_(constructor), this would be largely unchanged from the way
I've moved things now, only flipped. That is, where JS:String as the
more often-accessed page would be JS:String.prototype as it exists now
while JS:String_(constructor) would be JS:String as it exists now.
It is no concession of me to say that it is absolutely true that the
docs on String instances is far more likely to be the docs that users
want and that the accessibility as measured in number-of-clicks is
valid. The alternative proposal that I came up with would include
documenting the constructor and instances on the same page (see
Variant 2 in my post to Nickolay's talk page), but I was concerned
that ping-ponging between the two would be the more confusing path to
take. For example, readers, upon coming to a screenful of this <http://
developer.mozilla.org/en/docs/User:Sevenspade/
Second_organizational_variant/Error#Methods_of_the_Error_constructor>
would likely be discouraged and confused. This very closely resembles
the "draft" that Potappo started <http://groups.google.com/group/
mozilla.dev.mdc/browse_thread/thread/1ff81b80b75b6dff/
275c328e5d7d224d#275c328e5d7d224d>.
One thing to note, though, is that upon examining complaints here,
they don't really seem to be so much, "this is inaccessible; how am I
expected find this" but instead, "things aren't where they used to be;
I'm confused." Everyone posting thus far seems to have been previously
familiar with the Reference, and I'm assuming their experience went
something like this: they scrolled to the methods or properties
section in search of something and simply did not see it. Would
newcomers experience the same problem? I wouldn't expect them to.
They'd probably read the page top-down and notice the disambig-like
headers that were created in an attempt to prevent this problem. The
only /actual/ problem I see here is the number-of-clicks issue to get
to the desired content.
I propose two solutions:
1. Leave things as they are. One slight (albeit ugly) modification
would be to adjust the main JS Reference page to link to both the
constructor and the prototype object. It would look something like:
<native objects section>
Array, Array instances
Boolean, Boolean instances
. . .
Where "Array" and "Boolean" would remain the same, linking to their
constructor pages, while "Array instances" and "Boolean instances"
would link to JS:Array.prototype and JS:Boolean.prototype,
respectively. This has the benefits of the documentation being as it
was before my changes with people only having to adapt to clicking
"Array instances" to get at the information they want rather than
"Array."
2. An alternative would be to include the information from both pages.
That is, "Array" would contain the current contents of the page
"Array" concatenated with docs on Array instances, probably separated
by a horizontal rule or something, to maintain the discrete sections.
All in all, the goal of this whole thing is that the reference is
useful for everyone. If someone who is not "intimately familiar with
the nuances of JavaScript" simply wants to look something up, /it's
there/, but at the same time, if someone has an interest to really
learn the language, /it's there/. Unfortunately that wasn't the case
~2 months ago.
Again, sorry about the confusion this has caused with regard to trying
to find the origins of these changes. Like I said, the list didn't
really strike me as very productive about the discussion of changes at
MDC, and during the planning stages I simply directly sought the input
of Nickolay--who has been an active editor with knowledge of the
subject--and then at his suggestion, Sheppy, rather than bringing up
the topic and allowing discussion to stagnate until nothing really
gets done.
Seven...@gmail.com
-----
Oh, man. It seems my changes have proved to be unpopular.
I hope to make this post a catch-all for discussion on this issue, and
I guess we should use this thread as a centralized location for all
further discussion on this topic so things aren't so fragmented, which
definitely added to the problems and confusion in this case.
First thing,
On Jan 18, 8:12 pm, "Mike Shaver" <mike.sha...@gmail.com> wrote:
> It looks like SevenSpade has been making these changes, though I
> haven't seen discussion on the list of it; maybe elsewhere? Can
> someone connect with him to see about reverting these changes, and
> looking at other ways to improve the organization of the docs?
As for contacting me, the best way would be by leaving a message on my
MDC talk page. As much as I dislike the implementation of MediaWiki
talk pages, I find the use of the newsgroup to be far more unwieldy
and less productive (or at least used to).
Okay well, the beginning of this issue can be found here:
http://developer.mozilla.org/en/docs/User_talk:Nickolay#Inherited_properties.2Fmethods_in_JavaScript_Reference
The root of the problem was that the pages documenting the
constructors ambiguously mixed properties of the constructor itself
along with properties of the instances created by that constructor
with no mention of any distinction (actually, I think while making
changes I may have come across one infrequently accessed page that
made a poor and incomplete attempt at doing so). Simply put, /this was
a problem/. See the page documenting Number as it stood before:
http://developer.mozilla.org/en/docs/index.php?title=Core_JavaScript_1.5_Reference:Global_Objects:Number&oldid=54414
Note how there is no mention that MAX_VALUE is a static property while
On Jan 18, 8:12 pm, "Mike Shaver" <mike.sha...@gmail.com> wrote:
One thing to note, though, is that upon examining complaints here,
John J. Barton
> applicable, but this doesn't fix the mashed together docs on static
> and non-static members.
Ok I know this is off the topic of the post, but what is a static or
non-static member in Javascript?
John.
Mike Shaver
I believe Sevenspade means "property of the constructor" where he says
static; it's similar to "static" in Java, f.e., in that
String.fromCharCode is part of the String code, but can be used
without an instance of String to hand. It's dissimilar in some other
ways, but that's typically what people mean.
(I think it's close enough to the topic at hand, which is how to
describe JS such that it's clear to all comers. :) )
Mike
Mike Shaver
> As for contacting me, the best way would be by leaving a message on my
> MDC talk page. As much as I dislike the implementation of MediaWiki
> talk pages, I find the use of the newsgroup to be far more unwieldy
> and less productive (or at least used to).
The mailing list has been pretty quiet for a while, but I understand
and share your reluctance to get into bike shedding rather than making
changes to improve things. I suspect there's a happy medium between
holding a symposium on possible avenues of improvement and unilateral
overhaul, but it might not be worth finding? (Proposing an
improvement via a sandboxed/User page and then checking on the list
for show-stopping objections? We'd need to be careful to avoid
holding back improvements simply because there were other ways to
achieve the same improvement, but I think the navigational changes
here are disruptive enough that they would have benefited from some
more eyes.)
> The root of the problem was that the pages documenting the
> constructors ambiguously mixed properties of the constructor itself
> along with properties of the instances created by that constructor
> with no mention of any distinction (actually, I think while making
> changes I may have come across one infrequently accessed page that
> made a poor and incomplete attempt at doing so). Simply put, /this was
> a problem/.
Agree, definitely a problem; thanks for addressing it.
> Now, the reorganization that has been in planning since ~2005 attempts
> to rectify part of this problem by moving everything to the more
> appropriately titled /constructor/.prototype./member/ where
> applicable, but this doesn't fix the mashed together docs on static
> and non-static members.
Indeed. We at one point in the middle of last year we actually had
someone signed up to finish the reorg and merging of the various "new
in JavaScript 1.X" addenda, but they ended up abandoning the project,
and we didn't revisit it yet. :(
But now we have you, for which I offer "yay"!
> I opted to throw up a notice as the first thing that appears on the
> page (besides breadcrumbs) that closely resembles Wikipedia's
> disambiguation headers, which seem to be working for them, in the
> clearest language possible.
Yeah, I think that was a good innovation.
> These changes as a whole were up to now definitely still a work in
> progress and there are a few more things that need to be done along
> the lines of human-readable descriptions and stuff to be put under
> JS:About regarding various issues, like the one Potappo brought up
> about pseudo-properties <http://developer.mozilla.org/en/docs/
> User_talk:Potappo#Reply_to_Question_for_your_recent_JSRef_edits>.
Ah, OK, I didn't see that chain; is there a list of outstanding TODOs,
from your perspective? I'd definitely rather go forward rather than
back, if we can get to something that's a little closer to the
"approachable" side of the "approachable-pure" spectrum.
> It is no concession of me to say that it is absolutely true that the
> docs on String instances is far more likely to be the docs that users
> want and that the accessibility as measured in number-of-clicks is
> valid. The alternative proposal that I came up with would include
> documenting the constructor and instances on the same page (see
> Variant 2 in my post to Nickolay's talk page), but I was concerned
> that ping-ponging between the two would be the more confusing path to
> take.
I think we should press on this some more, because I think unification
has some compelling virtues here. One important one, IMO, is that
people often find these pages via search engines, and I think we don't
want them to wonder if they're on the "right" String page. Switching
back and forth
It doesn't help that we don't have a good, widely-used term for the
methods that hang off the constructor; "constructor method" sounds
like a method related to construction, "static method" is close but
brings in a lot of confusing baggage.
> One thing to note, though, is that upon examining complaints here,
> they don't really seem to be so much, "this is inaccessible; how am I
> expected find this" but instead, "things aren't where they used to be;
> I'm confused." Everyone posting thus far seems to have been previously
> familiar with the Reference, and I'm assuming their experience went
> something like this: they scrolled to the methods or properties
> section in search of something and simply did not see it. Would
> newcomers experience the same problem? I wouldn't expect them to.
> They'd probably read the page top-down and notice the disambig-like
> headers that were created in an attempt to prevent this problem. The
> only /actual/ problem I see here is the number-of-clicks issue to get
> to the desired content.
I think that's a problem, but I think the split nature of the page
makes it harder for people to feel that they really have the right
place for learn about Strings, and I think we should want them to feel
comfortable that they're all caught up when they finish reading the
page.
(I also think that people are largely blind to such notices, since
they are on the page to find out a specific something, rather than
read it top to bottom; see also extra-content warnings about security
problems, which are almost totally ineffective.)
> I propose two solutions:
> 1. Leave things as they are. One slight (albeit ugly) modification
> would be to adjust the main JS Reference page to link to both the
> constructor and the prototype object. It would look something like:
>
> <native objects section>
> Array, Array instances
> Boolean, Boolean instances
I don't think anyone would know which one they want to click there, really.
> 2. An alternative would be to include the information from both pages.
> That is, "Array" would contain the current contents of the page
> "Array" concatenated with docs on Array instances, probably separated
> by a horizontal rule or something, to maintain the discrete sections.
I think that's the better path.
> All in all, the goal of this whole thing is that the reference is
> useful for everyone. If someone who is not "intimately familiar with
> the nuances of JavaScript" simply wants to look something up, /it's
> there/, but at the same time, if someone has an interest to really
> learn the language, /it's there/. Unfortunately that wasn't the case
> ~2 months ago.
This touches on another key issue here: a reference is not a tutorial,
and I think that trying to make it be both makes it worse at both
jobs. We don't really have a tutorial, though, so the reference is
often pressed into service and suffers for it. I wonder if we could
just get by with a JavaScript_tutorials page linking to choice morsels
found on the interwebs, in order to relieve that pressure? Then we
could focus on the "person who is familiar with JS and wants to find
out a fact" use case, without competing pressures to bootstrap from
total ignorance.
> MDC, and during the planning stages I simply directly sought the input
> of Nickolay--who has been an active editor with knowledge of the
> subject--and then at his suggestion, Sheppy, rather than bringing up
> the topic and allowing discussion to stagnate until nothing really
> gets done.
To repeat myself, I don't think that you have to let discussion
stagnate in order to get wider feedback on it. If Sheppy's OK is
sufficient to go ahead without the discussion, it's ample to proceed
in the face of minor objections.
And finally, in spite of some concerns with the new structure (and
some very minor ones about how we got to such a sweeping change), I
must say that I'm _thrilled_ to see you step up so thoughtfully and
work to improve this critical set of documentation. This content has
been under-owned for quite some time, and it's fantastic to see
someone take initiative in improving it.
Mike
John J Barton
> On Feb 5, 2008 7:02 PM, <Seven...@gmail.com> wrote:
>
> Agree, definitely a problem; thanks for addressing it.
>
>> Now, the reorganization that has been in planning since ~2005 attempts
>> to rectify part of this problem by moving everything to the more
>> appropriately titled /constructor/.prototype./member/ where
>> applicable, but this doesn't fix the mashed together docs on static
>> and non-static members.
>
> Indeed. We at one point in the middle of last year we actually had
> someone signed up to finish the reorg and merging of the various "new
> in JavaScript 1.X" addenda, but they ended up abandoning the project,
> and we didn't revisit it yet. :(
>
> But now we have you, for which I offer "yay"!
Another "yay"!!
>
>> I opted to throw up a notice as the first thing that appears on the
>> page (besides breadcrumbs) that closely resembles Wikipedia's
>> disambiguation headers, which seem to be working for them, in the
>> clearest language possible.
>
> Yeah, I think that was a good innovation.
yes.
>
>> These changes as a whole were up to now definitely still a work in
>> progress and there are a few more things that need to be done along
>> the lines of human-readable descriptions and stuff to be put under
>> JS:About regarding various issues, like the one Potappo brought up
>> about pseudo-properties <http://developer.mozilla.org/en/docs/
>> User_talk:Potappo#Reply_to_Question_for_your_recent_JSRef_edits>.
>
> Ah, OK, I didn't see that chain; is there a list of outstanding TODOs,
> from your perspective? I'd definitely rather go forward rather than
> back, if we can get to something that's a little closer to the
> "approachable" side of the "approachable-pure" spectrum.
>
>> It is no concession of me to say that it is absolutely true that the
>> docs on String instances is far more likely to be the docs that users
>> want and that the accessibility as measured in number-of-clicks is
>> valid. The alternative proposal that I came up with would include
>> documenting the constructor and instances on the same page (see
>> Variant 2 in my post to Nickolay's talk page), but I was concerned
>> that ping-ponging between the two would be the more confusing path to
>> take.
>
> I think we should press on this some more, because I think unification
> has some compelling virtues here. One important one, IMO, is that
> people often find these pages via search engines, and I think we don't
> want them to wonder if they're on the "right" String page. Switching
> back and forth
One page has many virtues: I will always be lucky and the info will be
there.
>
> It doesn't help that we don't have a good, widely-used term for the
> methods that hang off the constructor; "constructor method" sounds
> like a method related to construction, "static method" is close but
> brings in a lot of confusing baggage.
Because these are not methods that hang off the constructor. String
isn't a constructor. Javascript does not have objects that *are*
constructors. These are just objects like everything else. Like every
other function you can use it to construct objects:
var str = new String(); // An object with String properties
var bar = new Foo(); // An object with Foo properties
Similarly there are not 'static' methods or fields. Its wonderfully
simpler that that other language ;-).
>
>> 2. An alternative would be to include the information from both pages.
>> That is, "Array" would contain the current contents of the page
>> "Array" concatenated with docs on Array instances, probably separated
>> by a horizontal rule or something, to maintain the discrete sections.
>
> I think that's the better path.
Yes, one page. How about these for titles of the two parts:
Array Properties
Properties of the Array Function.
Javascript doesn't have "Array instances" only "instances with Array
properties". So the description needs to avoid being pedantic while also
not perpetuating false comparisons.
One of the key reasons Javascript is widely used is that you can succeed
without knowing what ".prototype" means. But the flip side is that its
actually hard to understand advanced Javascript because there is so much
content around with red herrings leading you to think like C++/Java/etc.
Consider a small subsection at the bottom of every built-in type page
(last bit of the the "Properties of the Array Function" entry), like:
---
How Objects created with new Array() get Array Properties
An object gets Array Properties (link to first part) when it is created
with the 'new' operator:
var a = new Array();
In addition to running the method body of the Array Function (link to
the second part), the 'new' operator sets the newly created object's
'prototype' property equal to an object with the Array Properties (link
again). When Javascript looks for properties, it starts with the object
itself, then looks in the object's prototype. In this case, looking in
'a' for an Array Property will look in 'a' first then in 'a.prototype'
where the Array Properties have been added by the 'new' operator.
---
If something like this was repeated 30 times, it would not be a waste of
bandwidth, IMO.
John.
Seven...@gmail.com
> Proposing an
> improvement via a sandboxed/User page and then checking on the list
> for show-stopping objections?
I'm not sure what this means. Is it meant to be critical (that's kind
of a harsh word, huh?), that is, that I was suggesting that after
posting a comment to a user's talk page the absence of objections was
evidence that there were no objections, or . . . ? If so, that's not
what I intended. To me, the list just doesn't appear to be as
effective as desired. It's not just that it's not very active, but the
discussions it does contain are usually "how do I do this?" or "is
this a bug?" from those who don't realize that that this is a meta-
discussion for the documentation itself and not the subject of the
documentation. It just didn't seem to be a very serious form of
discussion, and so I had it written off as such.
That whole thing sounds overly defensive. It's not that there were no
objections on the list and so I proceeded; let me put it like this:
It wouldn't have mattered if there /were/ objections posted here,
because I wouldn't have seen them, again, due to the way I'd viewed
the list.
> > http://developer.mozilla.org/en/docs/User_talk:Potappo#Reply_to_Question_for_your_recent_JSRef_edits
>
> Ah, OK, I didn't see that chain; is there a list of outstanding TODOs,
> from your perspective? I'd definitely rather go forward rather than
> back, if we can get to something that's a little closer to the
> "approachable" side of the "approachable-pure" spectrum.
Not strictly related to this issue, in the course of editing whenever
I see something that needs to be changed in the form of fixing a
defect or just an enhancement that spans multiple pages, I think to
myself "Hmm, yeah, I should come back to this whenever I'm done," and
then forget what it is I wanted to do. So there are things which I've
felt need to be changed, although I can't think of them at the moment.
However, most have resembled what I described in that comment, i.e.,
things that need to be explained or clarified better, and for those
that are lengthy and face a lot of repetition, put on a common page
and referenced with footnotes or tags or something.
> I think we should press on this some more, because I think unification
> has some compelling virtues here. One important one, IMO, is that
> people often find these pages via search engines, and I think we don't
> want them to wonder if they're on the "right" String page. Switching
> back and forth
What were you going to say here?
> To repeat myself, I don't think that you have to let discussion
> stagnate in order to get wider feedback on it. If Sheppy's OK is
> sufficient to go ahead without the discussion, it's ample to proceed
> in the face of minor objections.
I'd like to clarify that Sheppy didn't full-on endorse this, but
merely said, "if it makes sense, do it."
> But now we have you, for which I offer "yay"!
> . . .
> And finally, in spite of some concerns with the new structure (and
> some very minor ones about how we got to such a sweeping change), I
> must say that I'm _thrilled_ to see you step up so thoughtfully and
> work to improve this critical set of documentation. This content has
> been under-owned for quite some time, and it's fantastic to see
> someone take initiative in improving it.
This isn't a recent development, but I guess making controversial
edits is going to garner visibility.
I'd like to reference Hixie's sentiment here: "Wow if I'd known that
removing Ogg from the HTML5 spec would get us that many new
subscribers, I'd have done it years ago."
Sheppy
reference. I've been watching this discussion with interest the last
few days, waiting to see if the people that have strong opinions would
hash things out before I step in, because I don't have any strong
preferences here.
Usability of the documentation is crucial, and clearly there's a
usability issue here, since there are plenty of people that aren't
happy with it.
My personal feeling is that the very small little link to the document
that most people are really looking for at the top of the main page
(such as http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:String)
isn't doing the trick. It's small, italicized, and easy to miss,
since it blends somewhat into the page layout. Looks like it might be
part of the breadcrumbs or whatever (at least when they were enabled).
I think we need to merge these pages back together, in order to reduce
the number of clicks people have to do in order to find what they
want. Although from a strictly technical standpoint having these
things on two separate pages may make sense, it doesn't work well from
a usability perspective.
Sevenspade is right; he asked if he could make this change, and I did
tell him that if it seems like a good idea to go for it. Clearly my
lack of strong opinions in this area made me say that more casually
than I should have. :)
Let's look at it this way: we tried it and we found it doesn't really
work. Let's see if we can work together (civilly) to come up with a
new way to do this that everyone can get on board with.
Eric Shepherd
Developer Documentation Lead
Mozilla Corporation
Mike Shaver
> On Feb 6, 12:19 pm, "Mike Shaver" <mike.sha...@gmail.com> wrote:
> > Proposing an
> > improvement via a sandboxed/User page and then checking on the list
> > for show-stopping objections?
>
> I'm not sure what this means. Is it meant to be critical (that's kind
> of a harsh word, huh?), that is, that I was suggesting that after
> posting a comment to a user's talk page the absence of objections was
> evidence that there were no objections, or . . . ?
No, not at all. I was just brainstorming about a way to accommodate
both your desire for fast progress and lack of bike-shedding, and my
desire for more visibility into upcoming changes to major docs. I
don't think you did anything wrong at all in a process sense, I just
have some quibbles with the resulting form (and as you point out, they
were amplified by my familiarity with the previous form).
> If so, that's not
> what I intended. To me, the list just doesn't appear to be as
> effective as desired. It's not just that it's not very active, but the
> discussions it does contain are usually "how do I do this?" or "is
> this a bug?" from those who don't realize that that this is a meta-
> discussion for the documentation itself and not the subject of the
> documentation. It just didn't seem to be a very serious form of
> discussion, and so I had it written off as such.
Yeah, I agree that we don't see a lot of meat-and-semantics
discussions on dev-mdc, though in part that feeds itself. I'm glad
we're having this one now, and I hope you find it productive enough
that you might be tempted back.
> > I think we should press on this some more, because I think unification
> > has some compelling virtues here. One important one, IMO, is that
> > people often find these pages via search engines, and I think we don't
> > want them to wonder if they're on the "right" String page. Switching
> > back and forth
>
> What were you going to say here?
Um, good question. I suspect something about how switching back and
forth between prototype and non-prototype methods feels like more work
for the user, and little gain.
> I'd like to clarify that Sheppy didn't full-on endorse this, but
> merely said, "if it makes sense, do it."
That's about as full-on as Sheppy gets; he's refreshingly supportive
of people who are ready to do real work. :)
> This isn't a recent development, but I guess making controversial
> edits is going to garner visibility.
>
> I'd like to reference Hixie's sentiment here: "Wow if I'd known that
> removing Ogg from the HTML5 spec would get us that many new
> subscribers, I'd have done it years ago."
Heh, quite. I'm definitely guilty of not keeping up on those edits in
proportion to my interest in them. Apologies for piling on at this
late date, and I hope it doesn't deter you from future work!
Mike
Seven...@gmail.com
> Well, here's my position on the state of the structure of the
> reference. I've been watching this discussion with interest the last
> few days, waiting to see if the people that have strong opinions would
> hash things out before I step in, because I don't have any strong
> preferences here.
> Let's look at it this way: we tried it and we found it doesn't really
> work. Let's see if we can work together (civilly) to come up with a
> new way to do this that everyone can get on board with.
I think the issue's been resolved. Now it's just a matter of when I
manage to get to it. I'll likely be able to do it this weekend.