As a detour from controversial language design issues, I was
wondering about opportunities to improve the ES spec usability:
- source availability: could the sources please be made available,
preferably in easily processed form, on github?
For draft standards, that would allow tracking progress and
discussions using git's and github's tools.
For official standards, that would allow re-processing for
alternate output formats (from the annotated standard in
HTML, to easily presented, cross-referenced and indexed
fragments for standard documentation hints in IDEs).
- cross-references:
Could the spec please make use of internal hyperlinks, to
facilitate internal navigation? The latest standard PDF can
only be navigated via the bookmarks (no cross-references,
no links from the table of contents, no index).
Could the bookmarks please be used to create "named
destinations", so that one can have external links to sections
of the spec?
- informative appendices on current practice:
Beyond the core language, there are at least two trends
that seem ripe for documentation. It might be too early
for prescriptive standardization, but if the interested parties
could identify common subsets, those could be included
as informative appendices, helping to prevent further
fragmentation:
Documentation annotations (@params, @result, @constructor, ..).
Type descriptions (DoctorJS and Closure seem to be using
different presentations at the moment, not sure about other
type-related documentation, checkers, and inferencers).
The idea would be to help tools and users to work together,
so that coders would not have to rewrite large parts of their
code base to switch tool chains, and so that all tools could
profit from common practice comments/annotations (think
of JS coders starting small, then suddenly wishing they had
the annotations to get Closure tools type checking; or think
about DoctorJS/DoctorJS--/.. infering types and documenting
them in a form Closure tools could check; or think about all
documentation using uniform type language).
Claus
http://clausreinke.github.com/
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
