Some spec usability issues (navigation, source, common practices)
# Rick Waldron (14 years ago)
es5.github.com is a good resource/starting point
http://es5.github.com is a good resource/starting point Rick On Mon, Oct 10, 2011 at 4:41 AM, Claus Reinke <claus.reinke at talk21.com>wrote: > 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 > es-discuss at mozilla.org > https://mail.mozilla.org/**listinfo/es-discuss<https://mail.mozilla.org/listinfo/es-discuss> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20111011/281dfda2/attachment-0001.html>
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 clausreinke.github.com
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/