Incorrect titles for method/property articles

MDN
#24

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.

#25

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:

#26

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.

#27

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

#28

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.

#29

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
#30

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
#31

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
#32

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
#33

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

1 Like
#34

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
#35

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.

#36

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
#37

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
#38

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
#39

Makes sense to me. :+1:t2:

#40

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.

#41

I agree, let’s just go with “XMLHttpRequest: open()” and be done with it. This is turning into an epic bikeshedding experience. :slight_smile:

#42

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?

1 Like
#43

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.