Web Docs

Michael Lewis mike at lew42.com
Sun Nov 5 12:29:38 UTC 2017


tl;dr Maybe there needs to be *an official blog*?  And/or summarize
decisions on MDN?

With the advent of transpiling, the state of the ES language is in greater
flux than ever before.  This group guides the development of the language
itself.  Then there are the implementers of your specifications.  I won't
pretend to know how it works, but it's safe to say, "it's like trying to
hit a moving target."  While standing on a moving platform.

When Andrea Giammarchi just wrote a post here showing an example of
extending the native Array "class", I wasn't aware that was even
possible/recommended.

I found an article from 2015 the other day, and scoured at it's age.  "This
is worthless! Nothing from 2015 is still valid today."  It's very common to
discover some new syntax, and not really know what it is.  Is it a babel
plugin?  TypeScript?  ES9000?  Where can I use it?  When should I use it?

If this is the "official" JavaScript Steering Committee, then it would make
sense that you should produce the authoritative documentation, and publish
the authoritative announcements/reasoning.

For example, when TC39 decided to remove properties from classes, there
should have been an announcement.  It seems like many people disagree with
this decision (myself included).

The MDN web docs are trying to be the go to place for all things web.  Yet,
I still google, "can i use es6 classes" to find browser compatibility
info.  Because MDN has already dissected "all the things" (they have
navigation and pages for all the topics you might discuss), documenting
certain design decisions on their site might make the most sense.  Maybe
you just start with a TC39 Design Notes sub page that can be added in
various places.

We should condense, summarize, and publish the enormously complex work that
is going on in these back channels.  Basically, extract the most important
stuff.  Extract the signal from the noise, and share it in an official
place.

What is this community's stance on documentation?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20171105/b67ce665/attachment.html>


More information about the es-discuss mailing list