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
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
-
the majority of people prefer the naming that we currently have, e.g
XmlHttpRequest.open()
. -
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()
. -
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. -
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
-
Most are professional developers.
-
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â
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âŠ
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!
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.
request.open() is in no way similar to XMLHttpRequest.open().
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()
.
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.
Nah, I donât think people are doing that
I should have been clearer here â the workflow I was more imagining was something like:
- They find an error in their code
- 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. - They find a page that looks useful (ours, hopefully)
- 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)
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()
?
Makes sense to me.
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.
I agree, letâs just go with âXMLHttpRequest: open()â and be done with it. This is turning into an epic bikeshedding experience.
Calling it
xmlHttpRequest
seems very likely to confuse people here.
Multiple people we talked to said that this would make no difference to them.
letâs just go with âXMLHttpRequest: open()â and be done with it
Multiple people we talked to said that they like to copy and paste terms from their code editor to search with, and trust results that look similar, i.e. the dot is more significant than we first thought.
Saying all this, I donât think there is actually a huge amount in it. I think the best options are either x.y()
or x: y()
. I still think we should call in the SEO expert to see how they think these would affect it. @sheppy, did you ask him to look at this already?
Iâve filed https://github.com/mdn/content/issues/3487 and fixed a few of the cases where the syntax snippets were misleading because of apparent copy-pasting.