OWD project: Document Temporal on MDN

[Elchi3]

This project proposes that Open Web Docs works on adding Temporal docs to MDN.

Repository: https://github.com/tc39/proposal-temporal
Spec: https://tc39.es/proposal-temporal
Docs: https://tc39.es/proposal-temporal/docs/

Problem statement

Temporal is a stage 3 ECMAScript proposal that aims to replace the JS Date API which has many pain points for web developers.

Temporal is a new API with a large surface area: the API reference is a few hundred properties and methods across 10 different types. It is not just a matter of writing a few PRs to get this documented. It likely 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.

See also tc39/proposal-temporal#1449 for the original request for MDN documentation.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Criteria	Assessment
Effort	Large. A few hundred properties and methods across 10 different types.
Dependencies	None
Community enablement	Possible. Temporal docs can be added collaboratively.
Momentum	High! A replacement for Date is long overdue. Currently stage 3, so probably not yet 100% stable. Implementation work starts now.
Enabling learners	Conceptual material should be added to understand dates, time, timezones, etc. a lot better.
Enabling professionals	Professionals and early adopters will want to know about Temporal as soon as it implemented.
Underrepresented topics / ethical web	N/A. (probably improves l10n/i18n, though)
Operational necessities	N/A
Addressing needs of the Web industry	Date is known as a pain point of the Web. Temporal aims help with that.

Proposed solutions

• Start work on documenting Temporal on MDN. Mark it as unstable for the time being, but make progress together with the implementations, so that docs are in shape when the first implementation is ready.
• Figure out how much is re-usable from https://tc39.es/proposal-temporal/docs/ and give feedback to these docs and the specification when possible.

Task list

A detailed content plan can be worked out as we go. Some first thoughts:

• The reference docs would live under the Standard built-in objects page tree.
  • This means pages for a few hundred properties and methods across 10 different types.
  • This will need compat data and interactive-examples for all reference pages as well.
• 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.

[meyerweb]

As part of my work at Igalia, my near-future project roadmap includes adding Temporal content to MDN, so Igalia (and I!) are fully in support of this proposal. My rough-draft plan was to start by documenting the API properties and methods, and using that experience to develop usage guides, but I’m open to realignment, particularly in ways that would support a group effort.

[meyerweb]

I decided to rough out part of a directory skeleton. You can find it here: https://github.com/meyerweb/content/tree/temporal. The intent is to set up the bare bones of a directory structure approach, for review and approval/disapproval by the group. Once set up locally, start from en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal in the browser and files/en-us/web/javascript/reference/global_objects in the file structure. Only now has a subdirectory at the moment. I patterned the overall organization (more or less) after the Date and Intl directories on MDN.

If this file structure makes sense, I can start filling things in. If it doesn’t, let’s determine what does make sense, and then we’ll have a path forward.

[meyerweb]

To be more specific and useful, you can look here on GitHub to see the directory structure (and the few index files, I suppose): https://github.com/meyerweb/content/tree/temporal/files/en-us/web/javascript/reference/global_objects/temporal

[Elchi3]

If this file structure makes sense, I can start filling things in. If it doesn’t, let’s determine what does make sense, and then we’ll have a path forward.

It does make sense and looks exactly what I would have expected :) Great work!

An option is also to have temporal docs sit in a branch unpublished for a while given it is not yet implemented or stable. I guess this would work well for new pages at least. Amendments to existing pages would likely lead to merge conflicts given all the activity on mdn/content, though.

[ryzokuken]

@Elchi3 what about merging the additions in, but with some descriptive text about how the implementation are WIP instead? Could that work?

[Elchi3]

Yes, that could work, too.

Do you think it is beneficial to have Temporal on MDN sooner rather than later? (even though the API is still unstable [I assume at least])

[meyerweb]

My inclination is to keep this in an unpublished branch until the API is fully documented, in the sense that every method/property/etc. has basic documentation and at least one example. At that point, I could see publishing with a warning note on Temporal pages similar to the one currently used for Date pages (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date).

A thing I discovered (being new to Temporal) is the overlap of methods, with() and toString() being two such. I’m pondering whether they should have their own subpages in each section—that is, creating Temporal/time/with/index.html, Temporal/yearmonth/with/index.html, Temporal/zonedDateTime/with/index.html, and so on—or if those methods which show up repeatedly should be in a separate unique place like Temporal/with/index.html or Temporal/methods/with/index.html which lists all of the objects in which they appear, with examples of using them in those objects.

I lean toward the latter: I think it should reduce the authoring and maintenance overhead, and would also naturally give readers a sense of methods that are common. My feeling is that someone clicking on a link to Temporal.time.with() and landing on a page that describes how with() works in general, plus shows examples from all the objects that allow it in one place, will learn more and more quickly than having to pogo-stick up and down a linktree to find out how with() is handled in each object, or which objects don’t have it.

That said, I’m definitely open to counterarguments on this, as I currently have a lot less experience with authoring MDN and API docs than the rest of you. In the end, I want to do what works best (on balance) for readers, not whatever is easiest or whatever I thought up.

[meyerweb]

Sorry, forgot to clarify in my last comment: this also applies to properties.

[meyerweb]

In case it helps, I compiled a survey of method and property frequencies in Temporal, and put it on on Google Sheets for ease of sharing. Note: Methods are in one tab, Properties in another.

[Elchi3]

Great to see you diving into the content planning here!

I guess the counterarguments are that the pages for from(), with(), etc. will need to disambiguate and talk about quite a few different contexts then. Maybe that's possible, though, because as you say, maybe describe things conceptional and then present specific examples given the various constructors.

I haven't looked closer but https://tc39.es/proposal-temporal/docs/instant.html#from and https://tc39.es/proposal-temporal/docs/duration.html#from are two from() descriptions and I guess I could imagine having two pages here that present the information. Just a feeling, though.

Not sure if comparable but to attempt to draw a comparison to existing MDN pages: the Intl API has format() on their constructors and we have separate pages:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/format
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/format

This has also to do with providing different interactive-examples, code examples, spec links, and compat data. The Intl APIs didn't land all at once and so having new pages as the API grows has been a good thing. (Not sure if Temporal grows, but usually all Web APIs grow sooner or later :)

[meyerweb]

I’ve found a couple of discrepancies.

• https://tc39.es/proposal-temporal/docs/#Temporal-now lists Temporal.now.plainTime(calendar) but https://tc39.es/proposal-temporal/docs/now.html does not.
• The TOC for https://tc39.es/proposal-temporal/docs/plaindatetime.html lists the properties era and eraYear twice.

[ryzokuken]

@meyerweb thanks! https://tc39.es/proposal-temporal/docs/#Temporal-now is outdated, I removed those methods but missed them there. Would you like to file an issue on the temporal repo?

[meyerweb]

Issues filed.

Progress: I picked the lowest-hanging fruit and filled out Temporal.now’s methods with pages of their own. They can be previewed in https://github.com/meyerweb/content/tree/temporal/files/en-us/web/javascript/reference/global_objects/temporal/now (or in your own local copy). Feedback is welcome, particularly if you spot anything incorrect or missing.

Note: As I write this, the methods plainDateTime() and zonedDateTime() lack examples, because I’ve been utterly shamelessly stealing the examples from https://tc39.es/proposal-temporal/docs/now.html, and those two don’t have examples for me to steal. Happy to take contributions if anyone has them; if not, I’ll make up my own based on other examples.

[meyerweb]

I’ve let commenting on this issue languish, but I’ve been making progress and am now very close to being ready for an actual PR. The reference pages are all done, modulo a few bits of structural cleanup and adding an advisory banner to the tops of all the pages. The content itself has been through review and editing at Igalia.

The branch of my fork is here for those who’d like to preview what I have: https://github.com/meyerweb/content/tree/temporal/

[justingrant]

@meyerweb That's great news!

Heads up: there are some changes coming to the docs from tc39/proposal-temporal#1492. We'll (hopefully) get approval for the underlying spec changes in next week's TC39 plenary meeting, after which we'll merge all the pending draft PRs, including for the docs. So it probably makes sense to wait to PR the docs into MDN until those changes are in the MDN docs too. There are no other significant docs changes on the radar, AFAIK.

Also, have you been tracking docs PRs in the Temporal repo and making parallel changes to your docs? Want to make sure that doc fixes make it into both places. There's only a few relatively minor changes recently, but there have been a few like these:

• Update object-model.svg tc39/proposal-temporal#1503
• FIx typo: PlainDateTime => Duration tc39/proposal-temporal#1512
• Correct + make runnable documentation code samples. tc39/proposal-temporal#1396

Also, once the docs are in MDN, will we remove the docs on the Temporal side and PR any future docs changes only into MDN?

Finally, what's the release plan? Will we wait until the first browser implementation ships before merging into prod MDN? Or does it make sense to put the docs in MDN even before a browser ships with Temporal?

[meyerweb]

Thanks, @justingrant! I’ll check the changes to make sure they’re reflected; I’ve been making some changes in parallel but I’ll make sure they’re in, and I’ll continue stay on top of any future changes.

On the question of the docs’ home, I personally would be fine with removing the TC39 docs and PR changes on MDN — but, as a newcomer to all this, I’ll defer to those with longer experience with Temporal and TC39 process. That said, removing the TC39 copies would need to wait until all the relevant documentation has been migrated. As of now, what’s ready for review is the reference pages. More discursive content (e.g., all the things linked in https://tc39.es/proposal-temporal/docs/#other-documentation) has yet to be converted to MDN. They’re next on my roadmap, to be clear, but not done as of this moment.

On the question of the release plan, there are currently discussions about how to label MDN content covering features not yet implemented (e.g., mdn/content#5118). Once that’s settled, I’ll update the PR with whatever solution is agreed upon, assuming it’s settled before there’s a shipping implementation, and be ready for merging.

I’m also planning to add interactive examples that incorporate the polyfill, and am currently in the process of determining the best way to structure that. Wrapped up in that will be determining the best way to provide the polyfill via MDN for people to download. I hope those two updates in particular will help speed adoption of Temporal, but they might lag behind initial publication of the docs on MDN. I hope that lag won’t actually happen, but it’s hard to be sure.

[meyerweb]

Update on changes: I brought over a few changes from tc39/proposal-temporal#1396 that were missed; the rest were already in place thanks to the timing of my work against that PR being merged. tc39/proposal-temporal#1512 was already represented, and tc39/proposal-temporal#1503 has yet to be migrated, so no problem there.

[hamishwillee]

@meyerweb @Elchi3 FYI Firefox has just added its stage 3 implementation behind a flag: https://bugzilla.mozilla.org/show_bug.cgi?id=1519167

So we're coming up to the time we will need MDN documentation. Can you give me a view on where you see your current updates? I.e. have you been tracking changes in the spec? How close are these docs to the existing status and MDN JavaScript docs conventions? I haven't look at what you have done yet at all - trying to understand the best way to move forward.

Have you been testing against polyfills?

@Elchi3 @wbamberg Does this need to be added for 2023 Q3/4 goals?

[Elchi3]

I'm closing this as not planned for the moment. When Temporal is ready, we will of course offer help with compat data and documentation as needed.

I think Eric's draft still lives at https://github.com/meyerweb/content/tree/temporal but it's quite likely that the specification has changed quite a bit since 2021. https://tc39.es/proposal-temporal/docs/ might be more up to date but I haven't checked.

[justingrant]

https://tc39.es/proposal-temporal/docs/ might be more up to date but I haven't checked.

This site is indeed kept up to date. There have been a few public-facing changes since 2021, but relatively few. And it'd be easy to look at git history to identify where changes were. So I'd assume that any docs work from 2021 is still almost entirely useable.

We're about to propose removing a lot of stuff from Temporal in response to implementers' size concerns, so that will cause corresponding removals from the docs, but docs of remaining functions should still be good.