Re: [mediacapture-fromelement] Migrate spec text to bikeshed.

With pleasure. 

The number 1 reason for me is that the .bs version is better at 
producing a legible specification, since most of the links to e.g. 
HTMLVideoElement can be simplified as {{HTMLVideoElement}}, 
{{HTMLVideoElement/ended}} etc, versus the ultra-verbose `<a 
href="...">`.  Having a mix of markup, links and text makes the Spec 
hard to read and, specially, to maintain.  

PR reviews also suffer with the current verbose situation since, for 
reviewers like yourselves, comparing the wording turns into an 
obstacle race for the eyes.  For example, the table of contents now is
 incorrect, but none of us has seen it because the section headers are
 buried in the markup.

Re. The added friction that you comment on the second paragraph.  A 
simple line is enough to compile bikeshed to html (from the 
README.md):
` curl https://api.csswg.org/bikeshed/ -F file=@index.bs -F force=1 > 
index.html`
so IMHO it's a price worth paying.  Bikeshed is used pervasively in 
WICG specs and in MediaRecorder and ImageCapture Specs of this WG.  We
 even have the boilerplate in place 
(https://github.com/tabatkins/bikeshed/pull/891) thanks to 
@dontcallmedom .

@alvestrand mentioned the possibility of a Travis job to generate the 
.html from the .bs and compare to the uploaded one to confirm that the
 user had not forgotten the compilation.  That would address your 
concerns, right?



-- 
GitHub Notification of comment by miguelao
Please view or discuss this issue at 
https://github.com/w3c/mediacapture-fromelement/pull/54#issuecomment-272315151
 using your GitHub account

Received on Thursday, 12 January 2017 23:19:23 UTC