RE: updated draft for discussion

Hi Shadi,

Yes, those are my main concerns, but just do not forget the positive aspects as well:
- The rewriting improved the tone and introduced better explanations in several sections.

Plus, on the other side: the version does not stick to the usual versioning system we were following (live Github draft > date-labelled draft > latest Editor's Draft).

Regarding the use of pull requests, I thinks this is a good idea (if you don't mind, for now I am sending my comments to this version on github issues as usual, as I had somehow now managed to track the changes; then we can link the issues to the discussion on the respective pull requests when these are ready).

Regards,

Samuel.

PS. I am afraid our messages got crossed: I had just submitted an issue to github with editorial corrections to the first sections, well, at least there they are for the record in case they are needed. 

-----Mensaje original-----
De: Shadi Abou-Zahra [mailto:shadi@w3.org] 
Enviado el: lunes, 23 de febrero de 2015 11:14
Para: Yod Samuel Martín; 'ERT WG'; 'Carlos A Velasco'
Asunto: Re: updated draft for discussion

Hi Samuel,

Thank you for your feedback!

Let summarize your main points (please correct me if I'm wrong):
  - The rewriting introduced technical inaccuracies
  - The restructuring introduced technical inaccuracies
  - There may be some merit to the editorial changes
  - The changes are just too overwhelming to process

You also suggested a good idea in using Github. What I could do is to put each section rewrite as a separate pull-request. We could then go over the sections one by one to compare the two versions, and to take the best of the two worlds (technical accuracy and improved style).

Carlos, would this be a suitable approach for you too?

PS: Please don't bother with grammar and typos at this stage, as each section will likely need changes anyway.

Best,
   Shadi


On 21.2.2015 12:31, Yod Samuel Martín wrote:
> Dear all,
>
> I am providing some comments in this e-mail, mainly related to general aspects and the editorial process, given that I have not been able to compile the comments for the content itself (and I am afraid these will take some time to complete).
>
> As Carlos had been working on the document edition for many months, editing changes once and again, then he had already got the most of it, and the evolution of the draft had reached a plateau when the FPWD was published, with only minor increments between versions. I guess that Shadi might not have felt fully satisfied with the most recent draft and, as the saying goes that two heads are better than one, he got down to take up the edition tasks for this version. I have mixed opinions regarding how we have arrived to this new draft: although I recognize the considerable effort made by Shadi, I also think this major revision somehow interrupts the workflow expected. The same applies to my views regarding the contents: while the overall tone is more suitable and many features are much better explained and easier to understand, other descriptions have become bogus now (e.g. content negotiation... ok, I said I would not be commenting here on the detailed contents).
>
> This ED represents a major revision departing from the previous draft. As an internal reviewer/commenter, I can say it is quite difficult to track changes with so many of them at once. Diff tools do not help much here. I would have preferred more incremental editions; although I understand that this was maybe the only way to handle such a large revision. Which brings me to the next point, I consider that the need for so many changes might have been raised beforehand. Anyway, I understand that this revision would require another round of publication as Public Working Draft.
>
> In any case, I would suggest taking advantage of github versioning facilities, which, by the way, encourage committing small changes and include their own diff tool as well. That way, it is easier to track small deltas that make a large change all together. Please do not hesitate to explain if there is any inconvenience to use github for these purposes, which I might not be aware of.
>
> Somehow related to this, a versioning problem I must point out, and which I think that should be solved soon. Now we have three "latest" versions:
> - The date-labelled Editor's Draft, which is the really most recent 
> version, corresponding to the ED we are now discussing 
> <http://www.w3.org/WAI/ER/WD-AERT/ED-WAET20141215> (by the way, are 
> all the acronyms in the URL path correct?)
> - The Live Version available on github <https://w3c.github.io/w3c-waet/WAET.html> which now has lagged behind the former.
> - The 'latest' Editor's Draft accessible at this URL <http://www.w3.org/WAI/ER/WD-AERT/ED-AERT> which is now outdated.
> In my understanding, what is usually expected is that the live version be a kind of night build, the date-labelled Editor's Drafts (if they are released) be somehow stable versions for discussion, and the latest Editor's Draft be always a mere alias of the latest date-labelled version.
>
> Please expect comments to the content in batches: as I explained, this might take some time. As Carlos pointed out, there are so many changes we would need to discuss, that this is not going to be straightforward at all (maybe not something as dramatic as 'from scratch', yet there are too many changes nonetheless). I think some sections are better worded now, thus I would discourage just reverting to the previous version. But I also think some others have introduced considerable issues that need to be tackled.
>
> Finally, I have already encountered no less than twenty editorial issues (typos, concordances, etc.). Although I will report them, I cannot assure I will spot out all of them, thus I would suggest editing the text on a web editor and automatically checking for orthography and grammar errors before fixing them in the original.
>
> And last but not least, I guess that no advances can be made in the 
> document until there is an improved agreement between the two 
> co-editors :-(
>
> Regards,
>
> Samuel.
>
>
>
> -----Mensaje original-----
> De: Carlos A Velasco [mailto:carlos.velasco@fit.fraunhofer.de]
> Enviado el: viernes, 20 de febrero de 2015 13:56
> Para: Shadi Abou-Zahra; ERT WG
> Asunto: Re: updated draft for discussion
>
> Dear all,
>
> Just for the record, and as one of the editors of the document, I just want to bring up my position on this.
>
> I disagree fundamentally with the suggested update prepared by Shadi for discussion. My main points are the following:
>
> - This summary approach was discussed months ago and discarded in one of our meetings, in favour of a more editorial approach.
>
> - It introduces some technical descriptions to which I do not agree.
>
> - It brings us to a stage in which basically we have to discuss the document from scratch, effort to which I do not have the allocation.
>
> On 02/18/2015 03:07 PM, Shadi Abou-Zahra wrote:
>> Dear group,
>>
>> After long delays, there is finally a new document for discussion:
>>
>> # Reference document with agreed changes:
>>    - https://w3c.github.io/w3c-waet/WAET.html
>>
>> # Suggested update for discussion:
>>    - http://www.w3.org/WAI/ER/WD-AERT/ED-WAET20141215
>>
>> Note that the suggested update includes significant rewrites for most 
>> sections, which may have introduced unintended technical inaccuracies.
>> This needs to be reviewed and discussed where issues are identified.
>>
>> Some of the key objectives for this suggested update was to:
>>    - Provide summaries for each feature, to give people an overview 
>> the first time they read the document, and to serve as a quick 
>> reference when people look back at the document (eg. to re-lookup a feature).
>>    - Tighten up the wording and describe each feature more clearly. 
>> For example, compare section  "2.1.5 Static code evaluation vs. 
>> rendered DOM evaluation" with the updated "2.1.5 Content Rendering".
>>    - Tried to give the headings shorter yet more meaningful titles; 
>> an attempt to organize the sections in a less arbitrary way; and lots 
>> of grammar and editorial improvements throughout.
>>
>>
>> Again, this is just a suggestion for discussion. Please compare these 
>> two versions and provide your thoughts and comments.
>>
>> Regards,
>>     Shadi
>>
>
> --
> Best Regards, Mit freundlichen Grüßen, Saludos, carlos
>
> Dr Carlos A Velasco
>     Fraunhofer Institute for Applied Information Technology FIT
>     Web Compliance Center: http://imergo.com/ · http://imergo.de/
>     Schloss Birlinghoven, D53757 Sankt Augustin (Germany)
>     Tel: +49-2241-142609 · Fax: +49-2241-1442609
>
>
> ---
> Este mensaje no contiene virus ni malware porque la protección de avast! Antivirus está activa.
> http://www.avast.com
>
>

--
Shadi Abou-Zahra - http://www.w3.org/People/shadi/ Activity Lead, W3C/WAI International Program Office Evaluation and Repair Tools Working Group (ERT WG) Research and Development Working Group (RDWG)


---
Este mensaje no contiene virus ni malware porque la protección de avast! Antivirus está activa.
http://www.avast.com

Received on Monday, 23 February 2015 11:04:32 UTC