Re: a couple of concerns

Hi Annete,

While adding the docs to the BP doc I intended to insert the text that  
is at the google docs, although I have added some examples and  
approaches for implementation that were missing in the google docs.

I made some changes, relative to the APIs BPs in other parts of the  
document, trying to accommodate the new text in the Best Practices  
document also, as you can see in this commit, for example:
https://github.com/w3c/dwbp/commit/264274fd3358d2a218248969e0ec2875eb9e8235

Finally, I opened the pull request before the voting, at 10Dec, as you  
can see here [1]. The objective of a pull request is to propose a  
change, not to commit a change. I asked for feedback, and asked for  
feedback at the google docs also, before commiting each change  
carefully.

I agree that we may need some tuning in our changes and freezing of  
the document in the group and I apologize if it was not clear that I  
was going to insert the text in the BP doc by accommodating all the  
best practices that were created at the google docs. I think we should  
try to pass thru all the changes that I've proposed to the BPs related  
to APIs an see if they fit in everyone expectations again, then.

I will wake up from my vacations one day before they end *just* to  
participate on the meeting tomorrow, so we can sort this things out  
with Phil's proposal.

Cheers,
Yaso

[1]  
https://github.com/w3c/dwbp/commits/264274fd3358d2a218248969e0ec2875eb9e8235/bp.html

Citando Annette Greiner <amgreiner@lbl.gov>:

> Thanks, Bernadette,
> I did agree with the inclusion of the new BP for REST APIs. In fact,  
> I've been pushing to include an updated version for a long time. But  
> when I reviewed the doc prior to the vote, the new BP to use REST  
> APIs was not yet in the doc at all. I honestly don't recall how long  
> before the vote I reviewed it, but it may have been just a few  
> minutes before it got added in. At any rate, my understanding at the  
> time of the vote was that that piece was not yet in but going to be  
> added as it appeared in the Google doc. When it did appear, it had  
> been edited from how it had appeared in the Google doc. There was  
> discussion during the meeting of the vote about making some small  
> changes in that section, so I assume that is the editing that took  
> place (clearly after the vote), but I didn't have an opportunity to  
> see the changes. Those late edits are the source of the trouble. I  
> agreed with the text in Google doc form but not with the edited  
> version. I do, however, also feel that the Google doc version should  
> have been included much sooner and been part of the doc when the WG  
> reviewed it. Getting a little stricter with ourselves about having  
> the document in a complete and frozen state for an explicit review  
> period should prevent this kind of thing from happening again.
> -Annette
>
> On 1/6/16 6:42 AM, Bernadette Farias Lóscio wrote:
>> Hi Annette,
>>
>> Thanks for your message. I understand your concerns, but I'd like  
>> to say that the changes that you pointed out were made on the  
>> document before the voting and not after the voting. The updates on  
>> the BP to use REST APIs were made one day before the voting and not  
>> after (we can check this on github commits [1]). Maybe the group  
>> didn't have a lot of time to discuss and evaluate this, but Yaso  
>> suggested the updates and  sent a message [2] to the group asking  
>> feedback about them. Then, before the voting, the editors made the  
>> merge of the updates.
>>
>> I just want to make clear that the editors didn't make any  
>> editorial change that could affect the meaning of the doc after the  
>> voting.  We are very careful with this because we understand that  
>> there are protocols and rules that have to be followed.
>>
>> kind regards,
>> Bernadette
>>
>> [1]  
>> https://github.com/w3c/dwbp/commit/d2ebb31e76cbd229f40c0997d622c3155de27911
>> [2] https://lists.w3.org/Archives/Public/public-dwbp-wg/2015Dec/0062.html
>>
>>
>>
>>
>> 2016-01-05 3:35 GMT-03:00 Annette Greiner <amgreiner@lbl.gov  
>> <mailto:amgreiner@lbl.gov>>:
>>
>>    Hi all,
>>    I’d like to raise a couple of issues that have been bothering me
>>    of late in our process for developing the DWBP best practices doc.
>>    The most recent version contained some last-minute changes that I
>>    disagree with, which points at two different issues.
>>
>>    First, we should not be making editorial changes that change the
>>    sense of the text after a vote to publish. While I’m sure that the
>>    editors have never intended to do that, the doc has been
>>    undergoing a flurry of post-vote changes each time, and these have
>>    sometimes affected the meaning. I am concerned about the pattern
>>    of delays in getting the document into a stable state and the lack
>>    of stability at the time of voting and immediately thereafter. I
>>    think we need to be voting on a document that is as we expect to
>>    publish it, including all changes. This would require a
>>    publication schedule with dates on which feedback is due and by
>>    which changes must be made, and those dates should be before the
>>    date on which we vote to publish.
>>
>>
>>
>>
>>
>>    Second, the most recent changes that prompted this concern are the
>>    changes to the text regarding the best practice to use REST APIs.
>>    I took some pains to include the two main approaches to using REST
>>    in my submission for that BP, and while I must admit that my
>>    writing was not successful in making the distinction clear, since
>>    it wasn’t clear enough to the editor to preserve it, I was
>>    surprised to see how far from my intent the published text
>>    appeared. I would be happy to give another try at teasing apart
>>    the two approaches. I do not feel that the current BP reflects
>>    what most web developers would consider best practices for
>>    developing with REST and REST-inspired architectures.
>>    -Annette
>>
>>
>>
>>
>> -- 
>> Bernadette Farias Lóscio
>> Centro de Informática
>> Universidade Federal de Pernambuco - UFPE, Brazil
>> ----------------------------------------------------------------------------
>
> -- 
> Annette Greiner
> NERSC Data and Analytics Services
> Lawrence Berkeley National Laboratory

Received on Friday, 8 January 2016 01:37:12 UTC