Specs lack detail useful for developers

[paulirish]

As web authors aren’t watching standards lists, much of the useful practical info about how these standards improve developer ergonomics is lost. Specs boil down the discussions for implementers and APIs but author-facing info isn’t prioritized. A good example: nearly all developers consider it a “trick” that you rev a comment in an appcache manifest in order to indicate the cache needs to be refreshed.

Specific issues

• As these details are not published in the specs, they don’t make it into developer documentation and thus, it takes months and years of experimentation to “discover” features and use cases of common features.
• In many cases, new specifications do not clearly outline use-cases that led to the specific implementations. Often, this information is clearly outlined in long mailing list threads, but those discussions are not synopsized in the specification.
• Specification authors and implementers don’t always think about feature detection, which lead to false positives and false negatives. This hurts a recognized best practice and encourages more UA sniffing.

Specific Suggestions

• Specification authors and editors should document intended use-cases and patterns for all newly developed features.
• When discussions on public mailing lists inform a specification, the editor of the specification should synopsize the results of the discussion in the specification.
• All new feature specifications should include a mechanism, in the specification, for detecting whether the feature is present in a particular user agent.
• The mechanism for filing “bugs” against a specification should be clearly indicated in the official location for the specification, especially during the drafting process.

Notes

The HTML5 specification’s “web author” mode is a very good starting point for improving the web author view of a specification. (http://developers.whatwg.org)

[paulirish]

looks like the feature detection was proposed already: http://www.w3.org/Bugs/Public/show_bug.cgi?id=13853

hixie asked for a web service to ping for each feature and the spec would show results inline.

[leobalter]

Too many has changed in the last 5 years, including some standards projects moving to GitHub.

This issue might need some updates in case of re-opening it.