Skip to content
This repository has been archived by the owner on Jan 24, 2024. It is now read-only.

Properly structure JS Intl docs #2537

Closed
bershanskiy opened this issue Dec 4, 2019 · 15 comments
Closed

Properly structure JS Intl docs #2537

bershanskiy opened this issue Dec 4, 2019 · 15 comments
Assignees
@Elchi3
Labels
Content:JS This is related to JavaScript content User Story Incremental value deliverable witin a Sprint / Iteration cycle and meeting part of an Epic's AC
Milestone
Echo Foxtrot (S1 ...

Comments

@bershanskiy
Copy link

bershanskiy commented Dec 4, 2019 •
edited by Elchi3
Loading

User story

As an MDN reader, I want consistent reference documentation, so I can find information reliably.

Acceptance criteria

Members of Intl are actually not child pages of Intl, so they need to be moved to match the existing URL patterns and they need to conform to the page recipes as outlined in linter requirements for JavaScript documentation.

To avoid breaking URLs in tables on MDN, probably the content pages should be moved first (with old URL redirecting to new URL) and only then the BCD should be updated.

Related issues

Tasks

Below is a complete list of moves (including children of children of Intl, which might be moved automatically when their parent is moved):

× javascript\builtins\Intl.json
@queengooborg
Copy link

(I'd actually not be the right one to CC for this; currently, my work is solely focused on BCD, and I have no page creation/movement permissions on the MDN docs!)

@bershanskiy
Copy link
Author

@vinyldarkscratch

I'd actually not be the right one to CC for this

I CC'ed you to inform you of the change and ensure the move is reasonable (aka I'm not miss-understanding something). If you prefer, I won't CC you in the future.

@queengooborg
Copy link

Ah, well thank you, I appreciate it! No worries -- I just thought someone else besides me would have a better opinion on the documentation structure. 😛

@chrisdavidmills
Copy link
Contributor

This should really be @Elchi3 's call. He is the MDN JS lead.

@Elchi3
Copy link
Member

Elchi3 commented Dec 4, 2019

We could do this, I guess...
I wonder why it was set up this way. I think it might have been to get these things into the sidebar more easily or something. Intl is a bit like a namespace object here: a content type we haven't defined as such, maybe we need to for stumptown.
If we are going to move these things around, we should also do it for all translations. JS docs are fairly well translated, I think, and it wouldn't be okay to just have the locales out of sync here. So, this is quite some page moving then.

How do we treat these namespace objects in API docs? Or in webextension docs? Maybe @wbamberg has opinions about the content structures, too. I think it would be great if we would first agree on how these things would be structured properly before we move a lot of pages.
(that said, this is unlikely a project I would just do now before going on holidays).

@bershanskiy
Copy link
Author

I wonder why it was set up this way.

That happened over 5 years ago, so I don't think anyone still remembers why. :)

I think it would be great if we would first agree on how these things would be structured properly before we move a lot of pages.

Absolutely!

@bershanskiy
Copy link
Author

Also, if Intl omission is intentional, then probably
https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales
should be moved to
https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/getCanonicalLocales

@wbamberg
Copy link

tl;dr IMO, @bershanskiy is right.

Intl is a bit like a namespace object here: a content type we haven't defined as such

A close analog to Intl seems to be WebAssembly, which we treat as an object with only static members, some of which are constructors. We put all these pages under the WebAssembly page (e.g. WebAssembly.Memory()).

It's probably beneficial to have pages that document an object's members be nested under that object itself, so this suggests that what we do with WebAssembly is right, and @bershanskiy is right to want to do the same for Intl.

One consequence of this is that given our sidebar implementation, if we want the objects they construct (like Collator) to appear in the top-level JS sidebar under "References/Built-in objects", then it looks like the pages must live directly underneath /docs/Web/JavaScript/Reference/Global_Objects.

So we can see that in the sidebar here, that Intl.Collator does appear, whereas WebAssembly.Memory doesn't.

That's probably OK. Noone has complained about this situation with respect to WebAssembly.Memory. And we will eventually rework the JS sidebars, and could address this when we do so, if we think it is important.

(This part is more possible things for the future.)

But also. We talked in London about whether it made sense to separate constructors from the objects they construct. To me (maybe only because my background is not JS?) it's really weird that we have these pages that are both, and that conflate constructors and the objects they create.
In fact you've already implemented this separation for BigInt.

What if we said:

  • Intl is an object that has a member Collator(), that's a constructor for Intl.Collator objects. It has a docs page under Intl, like all the other members. This page describes the constructor's syntax.
  • Intl.Collator is an object that has its own separate docs page. This page describes the overall object and lists its members.

If we did this, where would the page for the Intl.Collator object live?

  • Living under Intl seems good for coherence, but means slugs would collide for the object and the constructor, unless we took more steps to prevent that. Also, the page for the Intl.Collator object seems less closely tied to Intl than the constructor.

  • Or we could put it at the same level as the other "JS objects", although we might then want to stop calling it "/Global_Objects/" since they aren't global, whatever that means in this context. That would make it easier to list "all the objects" in the sidebar, assuming we wanted to do that. I think this option sounds better. But then, if we put the page at, say, "/JavaScript/Reference/Objects/Collator", it could in theory clash with the object constructed using the Foo.Collator() constructor.

How do we treat these namespace objects in API docs?

My sense is that we tend to do the latter thing, and put all the objects ("interfaces") at the top level under Web/API. But I'm not sure if the Web APIs have quite the same issue that we do here (and I'm also not sure if the Web APIs are a good choice to copy).

@Elchi3
Copy link
Member

Elchi3 commented Dec 11, 2019

Thank you for this excellent analysis, Will!

A close analog to Intl seems to be WebAssembly

I was looking around but couldn't think of an analog but there you have it! Nice find!

given our sidebar implementation [...]
And we will eventually rework the JS sidebars, and could address this when we do so, if we think it is important.

Yes, this. I'm fine with not constraining us any longer to our brittle sidebars but instead think how about we want the content to be structured and then make sidebars work with that later.

Separate constructors from the objects they construct.
In fact you've already implemented this separation for BigInt.

Yes, I still think we should go this way all throughout. It is something I want work on once I'm back in January.

So, for Intl, could it look like this?

  • /Intl (object, has no constructor)
  • /Intl/getCanonicalLocales (method)
  • /Intl/Collator (object)
  • /Intl/Collator/Collator (constructor)
  • /Intl/Collator/compare (method)
  • /Intl/DateTimeFormat (object)
  • /Intl/DateTimeFormat/DateTimeFormat (constructor)
  • /Intl/DateTimeFormat/formatToParts (method)
  • ...

That is, everything moves under Intl and we have dedicated pages for the objects and for the constructors (and we stop having "prototype" property pages).

@bershanskiy bershanskiy mentioned this issue Dec 11, 2019
Closed
29 tasks
@bershanskiy
Copy link
Author

Separate constructors from the objects they construct.
In fact you've already implemented this separation for BigInt.

Yes, I still think we should go this way all throughout. It is something I want work on once I'm back in January.

For sanity I created a separate issue #2571 for that.

This was referenced Jan 24, 2020
Merged
Merged
This was referenced Feb 12, 2020
Closed
Merged
@Elchi3 Elchi3 mentioned this issue Feb 19, 2020
Merged
@Elchi3 Elchi3 self-assigned this Apr 7, 2020
@Elchi3 Elchi3 added this to the Echo Foxtrot (S1 Q2 2020) milestone Apr 7, 2020
@Elchi3 Elchi3 added Content:JS This is related to JavaScript content User Story Incremental value deliverable witin a Sprint / Iteration cycle and meeting part of an Epic's AC labels Apr 7, 2020
@Elchi3
Copy link
Member

Elchi3 commented Apr 7, 2020

I've updated this to be a user stories per our sprint rules and I'm planning to do this work in our next sprint.

@Elchi3 Elchi3 changed the title Move docs about child elements of Intl under it Properly structure JS Intl docs Apr 7, 2020
@chinikes chinikes mentioned this issue Apr 7, 2020
Closed
8 tasks
@Elchi3 Elchi3 mentioned this issue Apr 21, 2020
Merged
@Elchi3
Copy link
Member

Elchi3 commented Apr 21, 2020

I've moved all pages and their translations.
The BCD update is in mdn/browser-compat-data#6015

@wbamberg
Copy link

wbamberg commented Apr 21, 2020 •
edited
Loading

Very nice, Florian.

This isn't exactly a suggestion for a thing to change right now, just a thing to clarify :). In the Intl page we have a section "Properties". If I understand correctly we have decided to call this "Constructor properties" - I understand that renaming the sections isn't in scope for this, so I'm not exactly asking for this change.

But the items in there are links to the object pages (e.g. Intl.Collator) not the constructor pages (e.g. Intl.Collator() constructor. Is that what we want? I think it would be better to link to the constructor, since that's what these properties actually are. What do you think?

@Elchi3
Copy link
Member

Elchi3 commented Apr 22, 2020

Thanks for the review, Will!

If I understand correctly we have decided to call this "Constructor properties"

Yes, I've renamed it.

But the items in there are links to the object pages (e.g. Intl.Collator) not the constructor pages (e.g. Intl.Collator() constructor. Is that what we want? I think it would be better to link to the constructor, since that's what these properties actually are. What do you think?

I agree constructor links are better. I've changed the links.

@Elchi3
Copy link
Member

Elchi3 commented Apr 30, 2020

The BCD update was merged. I think this is all done now.

@Elchi3 Elchi3 closed this as completed Apr 30, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@Elchi3 Elchi3

Labels
Content:JS This is related to JavaScript content User Story Incremental value deliverable witin a Sprint / Iteration cycle and meeting part of an Epic's AC
Projects
None yet
Milestone
Echo Foxtrot (S1 Q2 2020)
Development

No branches or pull requests
5 participants
@chrisdavidmills @Elchi3 @wbamberg @queengooborg @bershanskiy