MDN/TC39 collaboration

MDN
#1

I work in TC39, the JavaScript standards committee, and I’d like to work more closely with MDN on documentation for new language features. A few different ways we could do this:

  • Review MDN documentation for new features (how can we do this?)
  • Direct TC39 contributors who want to write documentation to MDN (I’m not sure how to send them to MDN to get started effectively though)
  • Once we get all of the standards-track-and-shipped-in-one-browser JS features documented, maybe we could move on to documenting not-yet-shipped proposals? Many people use these features through transpilers like Babel, and it’d be great to have MDN be a place to find documentation on their state, especially to feed back into the standards development process.

Thoughts?

5 Likes
#2

@littledan:

Thanks for talking with us about this, both in IRC today and here on Discourse!

I have a few ideas about this. Some I shared in IRC but will repeat here for others just joining in, and some I’ve thought about over the last few hours.

There are a few ways you can do this:

  • You can use the “watch” feature on the documentation site to receive emails whenever a page or a page and all its subpages are modified. By clicking the “watch” button on https://developer.mozilla.org/en-US/docs/Web/JavaScript, for instance, you can get email anytime the JS documentation changes. This may be overkill unless you use mail filters to get a better handle on things.
  • The Revision Dashboard provides a nice user interface for seeing what changes have happened recently, with the ability to filter by topic and so forth. There’s documentation for how to use the Revision Dashboard, too.
    As always, it’s incredibly useful for us to have people involved in the specification process for any technology participate in any or all levels of the documentation process on MDN.
  • Of course, we can also coordinate such that when new content is added, the writer directly pings the spec team for a review, if that works for them.
  • This is also a great option. Even if they only contribute a rough first draft, letting the core documentation team finalize things, that still has enormous benefits: it gets information to more people faster, it saves the writing team time, and it gives the writing team useful information to get started with in order to help track down details and produce clearer results.
  • We can certainly work with anyone who wants to help with this, by offering direct guidance and support. We also have a pretty substantial contributor guide with lots of details that are helpful.
  • Possibly. There would need to be some guidelines on just how “not-yet-shipped” things are, I think. And this stuff might be best kept in its own “Up and coming new bleeding edge awesomeness” section somewhere. Stuff to be determined through discussion.

As always, it’s incredibly useful for us to have people involved in the specification process for any technology participate in any or all levels of the documentation process on MDN.

4 Likes
#3

I would add a few pointers:

Hope this helps :slight_smile:

1 Like
#4

Hey Dan and thanks for reaching out!

I’d love to collaborate more with TC39 so that we could make decisions on what to document when and with better reviews. Traditionally, I’ve been focusing on documenting ECMAScript features that are implemented in Firefox as Mozilla is the main sponsor of MDN. It doesn’t necessarily need to be this way, though, and the community is of course always focusing on things they consider important.

If I understand it correctly, new ECMAScript language features start off with their own GitHub repo and are then later merged into the main ES specification. I think it would be interesting to see if such repo maintainers or feature champions would already think about documentation (just like they think about tests) and involve the MDN team early, so that we could outline what kind of docs would be needed on MDN and when we think it is a good time for actually publishing them.

Currently, docs come in quite late in the process (mostly when things ship in Firefox or Chrome). Sometimes we document things earlier, but then specs change or are abandoned (SIMD.js is such a case where we actually added a ton of docs :frowning: ). But I think there must be some sort of middle ground, and maybe the different feature stages that ES features have can help making decisions there.

As Sheppy and Sphinx mention, there are a variety of ways to get closer to the MDN pages and our community using some of the listed tools and I appreciate y’all coming closer to us!
I can also offer to get involved where spec work happens, so another approach could be to open “MDN docs issues” on specification repos and point me or the MDN team to them, so we can talk about how to proceed specifically for a new language addition and what MDN work would be involved. Let me know what you think about that and if TC39 folks would generally support having docs part of their workflow / spec tasks.

Florian

1 Like
#5

I’m really happy to hear all the positive and constructive direction for working together here. I’ve pointed TC39 delegates to this thread on our internal forum, and plan to present this opportunity at some of our meetings.

In the short term, if you want a input from TC39 on a particular piece of documentation and are not sure who to contact, you can email me at littledan@igalia.com and I’ll work to bring in people to help.

1 Like
#6

Another thing worth noting, and something @littledan alluded to earlier, is that the earlier we get writers involved at looking at and explaining new JavaScript features, the better the writing team is able to make suggestions about things that could be done differently for consistency with other APIs or language constructs before it’s too late to change anything.

That’s one of the things I think is best about a solid symbiosis between technical documentation teams and software engineering teams: writers often have a broader “big picture” view of the world from the point of view of the typical software writer or web developer, which gives us a perspective that can be very useful when looking at a new API or language feature during the middle stages of its development. Catching quirks before it’s too late can be a huge win, even if it happens only rarely.

1 Like
#7

I’m really loving the details that @sheppy and @fscholz have provided—it’s the first time I’ve seen all of the varied tasks that I do written down in one place.