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.)