What's the plan to get Temporal docs into MDN?

[justingrant]

This is a placeholder issue to track how we'll bring Temporal to MDN documentation. I assume the current Temporal docs would be a helpful starting point, but I also assume that the MDN folks will have well-informed opinions about these docs. ;-)

[littledan]

cc @Elchi3

[justingrant]

Here's the docs on MDN for how to add new docs to MDN: https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference

[Elchi3]

I'm happy to help here. Are there opinions on when is a good time for MDN to have Temporal docs?
Usually, MDN documents Web platform technologies only if there is at least one implementation. Are we nearing that point?

The Temporal docs here are cool! Would be nice if we can borrow from it maybe (license?).
I see the docs also warn about not using Temporal yet. So, I guess MDN would need to warn strongly too if we had docs today.

Some pointers / thoughts:

• The reference docs would live under the Standard built-in objects page tree. I haven't counted how big Temporal's API surface is but looks like there is quite a bit.
• Date and DateTimeFormat docs might need some pointers to the new / better Temporal APIs.
• If Date or certain APIs are deprecated or considered legacy now, we should maybe write a guide how to migrate to Temporal (this was proposed in Migration guides for deprecated apis mdn/content#2696) and maybe compare legacy Date APIs and Temporal APIs side by side.
• The JS Guide has a chapter on Numbers and Dates. I guess it makes sense to split this up and have a dedicated chapter just for Date and Time. I reckon some guidance around when to use Date, when Temporal and when the Intl API is needed, too? And there is likely a compatibility story to tell there, too.

Probably a lot more to do. I can write a more detailed content plan if we're ready to get going with this. This will need compat data and interactive-examples for all reference pages as well, for example. So, plenty of things to work on here :)

[justingrant]

This is great! I agree with the suggestions you noted above. You're correct, it's quite a large surface area: the API reference is a few hundred properties and methods across 10 different types, and a lot of accompanying conceptual docs outside API reference. The docs are in docs/*.md in this repo if you want to get a sense of the scope. Perhaps the same order of magnitude as the current Intl docs? (Although I suspect the Temporal docs may be larger than Intl in word count.)

Implementers are just getting started so implementation launch is at least a few months away. @sffc do you know the latest rough estimate for when the first implementation will come online?

@Elchi3 Given the huge size of these docs, I assume it will take a few months from project kickoff to docs being live in MDN. Would it makes sense to start work on the docs in parallel to implementations so that there won't be a few-month gap between implementation release and MDN docs for it? If yes, then how long before the first implementation launch should we kick off the MDN work?

@ptomato - are there any license issues preventing MDN from using the Temporal docs? I assume not but I'm not an expert on licensing.

[Elchi3]

Thanks @justingrant 👍

@Elchi3 Given the huge size of these docs, I assume it will take a few months from project kickoff to docs being live in MDN. Would it makes sense to start work on the docs in parallel to implementations so that there won't be a few-month gap between implementation release and MDN docs for it? If yes, then how long before the first implementation launch should we kick off the MDN work?

It likely makes sense to get a bit ahead here and work on docs early to avoid the few-month gap you describe here. I filed openwebdocs/project#29 so the Open Web Docs group can discuss when is a good time to get into this.

[sffc]

Implementers are just getting started so implementation launch is at least a few months away. @sffc do you know the latest rough estimate for when the first implementation will come online?

I don't expect V8 or SpiderMokey to land before Q4 at the earliest. Don't know about JSC.

[Ms2ger]

CC @meyerweb

[meyerweb]

I’ve made an initial run at adding a couple of sections of the API to a local MDN branch, but I need to go back through and make sure it’s up to https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference standards before asking others to look at it.

Also, I basically ported the content from https://tc39.es/proposal-temporal/docs, with mostly minor editorial tweaks. If that’s a problem for licensing or other reasons, someone please let me know so I can adjust. (Probably by creating bare skeletons of pages for others to fill in, since I am poorly qualified to write original JavaScript API documentation.)

[meyerweb]

Update: I have two and a half sections up to MDN standards (anyone is free to pull https://github.com/meyerweb/content/tree/temporal locally and explore). Currently working to resolve possible licensing incompatibilities between Temporal’s BSD license and MDN’s CC-BY-SA-2.5 license, either through relicensing or a special permission grant.

Speaking of, is there a guide on how to add attribution to MDN content if it came from another source and was re-used with permission? If that’s even a thing?

[ptomato]

@meyerweb I've built your branch locally and it's such a great feeling to see this stuff actually on an MDN page! What kind of feedback would be most helpful to you at this point?

[meyerweb]

What kind of feedback would be most helpful to you at this point?

Information architecture and organization feedback is highest priority, so that I don’t end up creating a sub-optimal file structure. So if there’s a feeling that there’s a better way to organize the various pages, now’s definitely the time to tell me, before the whole thing gets built out.

After that, any content patterns that should be improved—by that, I mean things that occur on multiple pages. That could be as simple as “you should replace this term you always use with this other term” or as complex as “there’s a persistent misrepresentation of how this thing is used and it needs to be corrected”.

After that, typos, individual page corrections, missing examples, etc. All missing content has a TK string, so multi-file searching the directory for TK will show where things still need to be filled in.

All that said, I have content authoring on pause until the licensing situation is clarified and I know how to proceed. I’m resisting building out stub pages for all the classes/properties/methods/etc. that I haven’t done, because I’d rather a page that isn’t fleshed out just create a broken link. Much easier to keep track of what still needs to be written that way.

[meyerweb]

With the recent closure of #1468, I’ve restarted the migration. Currently 6 of the 11 classes in the Temporal API are complete to at least a first-pass level; that is, all content for those sections is in place, but has not been peer-reviewed. https://github.com/meyerweb/content/tree/temporal

[justingrant]

Heads up @meyerweb - We've done a few recent PRs with minor docs changes that you might want to use.

I labelled PRs that looked like they contain docs fixes: https://github.com/tc39/proposal-temporal/pulls?q=is%3Apr+label%3Adocumentation, although it's probably easier to just look at commits in the docs folder.

[meyerweb]

Heads up @meyerweb - We've done a few recent PRs with minor docs changes that you might want to use.

Got ’em — thanks! (And sorry for the delay; holidays ’n’ all ’at.)

[Josh-Cena]

FYI mdn/content#37344.

Should I tag someone for technical review, once it is ready?

[Josh-Cena]

I have a question. I hope it's fine to ask here. I got hung up on this statement:

Days in a month are not always continuous. There can be gaps due to political changes in calendars. For this reason, instead of looping through a month from 1 to date.daysInMonth, it's better to start a loop with the first day of the month (date.with({day: 1})) and add one day at a time until the month property returns a different value.

Can anyone provide an example where date.with({ day: 1 }).day !== 1 and/or nextDay.month === date.month && nextDay.day !== date.day + 1?

[legowerewolf]

Britain, 1752. September 2 is followed by September 14.

[justingrant]

A modern example: December 30, 2011 didn't exist in Pacific/Apia, because the country of Samoa changed to the other side of the international date line to better align with its trading partners in Asia. So it skipped from Dec 29 to Dec 31 that year.

Source

[Josh-Cena]

Britain, 1752. September 2 is followed by September 14.

I am aware of the Gregorian calendar shift, but isn't that due to the adoption of a new calendar? I am unable to get it working, at least with the polyfill:

for (let y = 1580; y < 2000; y++) {
    for (let m = 1; m <= 12; m++) {
        const month = Temporal.ZonedDateTime.from({ year: y, month: m, day: 1, timeZone: "Europe/London" });
        for (let day = month.with({ day: 1 }), i = 1; day.month === month.month; day = day.add({ days: 1 }), i++) {
          if (i !== day.day) throw [y, m, i];
        }
    }
}

A modern example: December 30, 2011 didn't exist in Pacific/Apia, because the country of Samoa changed to the other side of the international date line to better align with its trading partners in Asia. So it skipped from Dec 29 to Dec 31 that year.

Thank you! I am able to reproduce this. If I understand correctly though, this is due to an offset change, not a calendar change, and the related verbiage is already discussed and removed in #2495. I wonder if I can get the same behavior without using a ZonedDateTime, hopefully with a PlainDate.

[justingrant]

Thank you! I am able to reproduce this. If I understand correctly though, this is due to an offset change, not a calendar change, and the related verbiage is already discussed and removed in #2495. I wonder if I can get the same behavior without using a ZonedDateTime, hopefully with a PlainDate.

Ahh, good point. This is indeed a different case, because calendars don't know about offsets.

That docs text was written at a time when Temporal had the ability for users to create custom calendars. This feature was removed earlier this year to reduce the complexity of Temporal. And I believe (@sffc can correct me if I'm wrong) that all the currently-supported built-in Gergorian-derived calendars are proleptic, meaning that they don't honor the Julian=>Gregorian changeover that happened in the 18th century. Instead, a proleptic Gregorian calendar will simply act as if the Gregorian calendar was used forever.

However, I know that @sffc and others have been considering introducing a built-in calendar that is non-proleptic. If that calendar is introduced, or if a future Temporal-extending proposal adds back the ability to add custom time zones, then the docs text above will be needed.

TL;DR - I'd recommend keeping that text in the docs because it's smart for future-compatibility, even if it's not needed with today's built-in calendars. It certainly won't hurt!

Also, it's good practice so that ZDT code and PlainDate code will return the same result for that Pacific/Apia case.

[sffc]

Incrementing day as shown above should skip the day in Pacific/Apia that didn't exist if ZonedDateTime was used, but it won't affect PlainDateTime since it has no location attached to it. This is not exactly the same issue as change dates, which also impact PlainDateTime.

I believe all engines are currently using proleptic gregorian. When they add a julian-gregory calendar with a change date, I don't believe the behavior has been hammered down, but there are two possibly reasonable behaviors:

1. The day numbers are continuous, retaining the arithmetic invariant, but the formatting changes. For example, PlainDate.from({ calendar: "julian-gregory-1752", year: 1752, month: 9, day: 3 }) would succeed and return a date with those coordinates, but it would become "December 14, 1752" when formatted.
2. The day numbers have a discontinuity, breaking an arithmetic invariant, but keeping the day numbers consistent with the formatted output. PlainDate.from({ calendar: "julian-gregory-1752", year: 1752, month: 9, day: 3 }) would fail/constrain.

But, this seems like not the best issue to discuss this topic. The title of the issue is about MDN.

[Josh-Cena]

Hello! mdn/content#37344 is ready for a technical review, if anyone's interested.

[MichaelDimmitt]

Cool, mdn/content#37344 got merged!
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal

[Josh-Cena]

Ah yes, I forgot to share that news here. Please check it out and let us know if anything's incorrect.

[ptomato]

I plan to take a detailed look at the pages soon.

@Josh-Cena Sorry I didn't have the opportunity before it was merged, but if I have any feedback I'll be diligent about filing issues and PRs.