Incorrect titles for method/property articles

Thanks, Janet. Yes, I made the change to consistently use “.prototype.” throughout the ECMAScript docs in 2013. I wanted this to be correct and closer to how the (at that point newish) ES6 spec named these things. I think it is important to clearly document static vs prototype built-in members. In 2013 I also discussed this with a few members of the MDN team, but we couldn’t agree on doing this throughout all Web API docs, so I just went with doing this for JS. I’m sorry if this created a somewhat inconsistent mess. Result of strong opinions colliding :slight_smile:

Now, 5 years later, I think we should revisit this, possible do some user research and agree to consistent titles based on user needs (web developers) rather being so opinion based.

I like “Array#push” as it is shorter than “Array.prototype.push”, but then you have to know what “#” stands for (and yes, private fields use “#” so this is a no-go now, I think). I guess now many also probably don’t know what “.prototype.” actually means. So, I maybe “Array: push() method” would work, and in the first summary sentence would have consistent wording that this is a prototype method. Worth doing research on.

Thanks Chris for going into this. This one isn’t easy.

Jean-Yves is also right, need to double check how this is used in macros. domxref and co come to mind, but also sidebars which list “properties” and “methods”. I think in JS docs you can easily differentiate statics vs prototype members in the sidebar (look at Array). I think for me it is even more import how it looks like in the sidebar than how it looks like in the page title or the h1. Right now this is coupled, but we could implement this differently so that the sidebar does not show page titles but something else.

So, I also added .prototype. because I like the sidebar like it is with the current titles:

Methods

  1. Array.from()
  2. Array.isArray()
  3. Array.of()
  4. Array.prototype.concat()
  5. Array.prototype.copyWithin()

If we’re changing the titles now, it would look like this:

Methods

  1. Array: static from() method
  2. Array: static isArray() method
  3. Array: static of() method
  4. Array: concat() method
  5. Array: copyWithin() method

So, doesn’t this look cluttered? Maybe sidebars should be thought through differently and be decoupled from the page title? Worth user testing as well in my opinion.

Florian

Yup, agreed. But I believe it was @sideshowbarker somewhere above suggested the idea of excluding the “method” and “property” words in sidebars, so we’d end up with something more like

  1. Array: from() [STATIC]
  2. Array: isArray() [STATIC]
  3. Array: of() [STATIC]
  4. Array: concat()
  5. Array: copyWithin()

Think of [STATIC] as being like one of those little badges we use, like for READONLY, or whatever. I think this’d look best.

1 Like

I like the idea of using user research. I have a strong suspicion that despite the views of a few folks in this thread, modern web developers actually do know and care what .prototype. means. But I can see I wouldn’t make progress against the folks here without data backing up that intuition.

3 Likes

Happy to do more research on this, but if memory serves well, almost nobody among the users we have interviewed (more than 20 IIRC) was able to make sense of it. We could go back and re-evaluate those interviews.

For what it’s worth, I didn’t (and still kind of don’t) understand the importance of .prototype.

I like the idea of resolving this with user research :slight_smile:

This is a good point. We will have to handle this. But it should not be difficult to update macros around it. When generating the sidebar we can easily enough pull out from the title the information we actually need in the sidebar and just use that. Simple logic lets us remove everything up to and including the ": " at the beginning, excise the last word to decide which section of the sidebar to put the item in (methods, properties, etc). If the first word remaining is “static”, put it in the “static s” list, otherwise the regular list for that type of item.

Hi all,

Just wanted to share that we sent a survey out over social media and have now finished analyzing the results to help assess which naming option would be most appealing to people. Here are the results: https://docs.google.com/presentation/d/1c5aXrGD_3J2NlI9K2yFBd-GX1VBUwa4S0Vw5QPl-_0g/edit#slide=id.p.

The main findings

  1. the majority of people prefer the naming that we currently have, e.g XmlHttpRequest.open().

  2. We learned that adding .prototype, although it is technically correct, is verbose and more difficult to read, e.g. XmlHttpRequest.prototype.open(). Adding “method” to the end is unnecessary because it is implied by ().

  3. Devs tend to prefer to write in something to search for that matches what they tend to actually use in their code editor, so, not *.prototype.*. We were told this multiple times over related twitter conversations we had when sending out the survey.

  4. What they mainly assessed the naming options on were: clarity, closeness to actual code for ease of copy and paste, short and to the point, ease of scannability and accuracy/correctness.

##About survey participants

  1. Most are professional developers.

  2. Most feel that they understand what static methods and prototypes are.

Let me know what you guys think of the results or if you have any questions!

Next steps

We will proceed with recruiting a few developers to invite to do a usability test/interview to understand what their expectations are when they’re searching for such features.

We are wondering whether a solution would be to simply remove the dot from between the interface name and the member? So instead of

XMLHttpRequest.open()

we’d have

XMLHttpRequest open()

?

That would no longer be explicit incorrect syntax, so would no longer be a problem to Domenic and the other spec folks (?), but we’d have to test whether this would be disastrous in some other way (e.g. would it ruin SEO?)

If this is no good, is there any other alternative pattern that would please the spec folks as well as our main target audience?

Credits and further reading

Thanks to Shi Li for composing and running the survey.

The full unfiltered survey results are here: https://data.surveygizmo.com/r/28049_5be076be70cde8.17076831

I propose XMLHttpRequest: open(). It’s equally short, doesn’t match actual syntax, but grammatically works, too.

That having been said, I do have some concerns from an SEO perspective. We’ve been advised by one or the SEO experts we’ve talked to always have more descriptive titles than this. I’ve asked our on-staff SEO expert to weigh in on this and will share that information when I hear back from him.

Your suggestions sounds reasonable to me, but I’m still not sure.

To add another interesting datapoint, Shi Li conducted a live interview with a regular MDN user, and had this to say:

“when I asked him which he preferred: xmlhttprequest.open() or xmlhttprequest open(), he preferred the first because he wants to copy and paste it into his editor”

“In the survey, he wrote: It’s closest to the written code. When I search for documentation on a specific code API, function, etc. I search on its literal name in code just like when I look up the definition of a function or class within my IDE or the web console with ‘jump to original location’. Doing it another way, I think opens up the possibility of getting documentation for something completely different b/c identifiers in code may be similar in name even though they’re completely different.”

“he’s someone who uses mdn every day”

1 Like

The thing that XMLHttpRequest.open() is something you can copy and use in code is why it’s historically how we’ve done it, and perhaps it should stay that way for that reason. I would still like to add “Method” or “Property” or whatever to the title, at least…

1 Like

You cannot copy and use it in code. That’s why it’s so frustrating. There is no static open() method, so attempting to copy and use that code will result in an exception due to trying to call a non-existent method.

Contrast this with cases like URL.createObjectURL(), which you can copy and use. But MDN does not distinguish between these, misleading you into thinking that open() is usable in code like createObjectURL() is!

1 Like

I respectfully disagree. When you use it in code, you would first write something like

var request = new XMLHttpRequest()

Then to use open(), you would actually write something like

request.open()

This second line is what we are on about — this is similar to the titles of the MDN reference pages. At no point in their code is your average web developer going to write

XMLHttpRequest.prototype.open()

Unless they are doing some kind of weird override thing, which generally isn’t a good idea anyway for common purposes.

I’m not saying I disagree or agree with the current titling necessarily, but this is where it comes from.

1 Like

request.open() is in no way similar to XMLHttpRequest.open().

1 Like

It is in that they both follow the pattern x.y(). To your average web developer, it is similar. When we did research on the terms people searched for to get information about open(), they were searching for strings like request.open() and xhr.open().

1 Like

This also raises the question: Are programmers copying and pasting from page titles? I would expect them to be more likely to copy and paste from code examples, or lacking those, from syntax definitions.

Either of those latter two would be acceptable page titles. It’s XMLHttpRequest.open() that is specifically bad, because it implies a static method which does not exist on the XMLHttpRequest class.

1 Like

Nah, I don’t think people are doing that :wink:

I should have been clearer here — the workflow I was more imagining was something like:

  1. They find an error in their code
  2. They and copy and paste the line the error is being thrown on out of their code editor (e.g. request.open()) and into their search engine of choice.
  3. They find a page that looks useful (ours, hopefully)
  4. They find a useful code snippet that works, and copy and paste it out of our page and back into their code editor

So the title isn’t going to be directly involved in the copy pasting, but it will inform their choice of what page to look at, and hopefully make that page more likely to be found (SEO and all)

1 Like

That’s really interesting input. Those would seem more wrong to me at first glance, but more right as I thought about it more.

Maybe we could solve this by simply lower camel casing all the interface names to imply that they are instances rather than class names (where appropriate), so for example xmlHttpRequest.open() ?

1 Like

Makes sense to me. :+1:t2:

Maybe we could solve this by simply lower camel casing all the interface names to imply that they are instances rather than class names (where appropriate), so for example xmlHttpRequest.open() ?

I hate to drag this out further but I don’t think this is a good idea. Part of the role of the XMLHttpRequest bit is to scope open(): that is, to say it belongs to an XMLHttpRequest object. Calling it xmlHttpRequest seems very likely to confuse people here.

If we really want to do away with ., why not XMLHttpRequest: open() as suggested upthread? Looking at the reasons people gave in the survey for preferring XMLHttpRequest.open(), this seems to have most of the same advantages while only being 1 character longer.