Re: Working on FPWD, more to do

Bernadette,

Interesting observations and now I am rereading Annette and Phil's conversation. 

Unless I am mistaken this is a  editors decision. How do the BP editors feel about this?

Eric 

Sent from my iPhone

> On Feb 3, 2015, at 2:54 PM, Bernadette Farias Lóscio <bfl@cin.ufpe.br> wrote:
> 
> Hi Phil,
> 
> After the last discussions, I checked (again) other BP documents and i
> saw that the Mobile doesn't use RFC statements. Then,  I was wondering
> if we really need to have normative statements in the DWBP.
> 
> My suggestion is to remove all RFC statements.
> 
> cheers,
> Bernadette
> 
> 2015-01-30 10:12 GMT-03:00 Phil Archer <phila@w3.org>:
>> I've been thinking about this some more and doing some digging around.
>> 
>> Here are three other W3C Best Practice documents:
>> 
>> Mobile Web http://www.w3.org/TR/mobile-bp/
>> Linked Data Platform http://www.w3.org/TR/ldp-bp/
>> XML Signature http://www.w3.org/TR/xmldsig-bestpractices/
>> 
>> It's perhaps noteworthy that *none* of these include *any* normative
>> statements in their best practices. The last two are Notes, so they are not
>> normative anyway, but the mobile one is a Rec.
>> 
>> Incidentally, the Spatial Data on the Web WG that kicked off last week
>> (a.k.a 'my other group') is producing a BP document and, at on member's
>> insistence, that is being written as a Note, not a Rec, precisely because,
>> in their view, best practices are never normative.
>> 
>> I don't think that answers all your point, but it suggests that we *might*
>> want to remove all RFC2119 statements entirely.
>> 
>> Phil
>> 
>> Tracker, this is ISSUE-146
>> 
>> 
>> 
>> 
>>> On 29/01/2015 21:51, Phil Archer wrote:
>>> 
>>> Thanks for this Annette,
>>> 
>>> In my comments below I begin by disagreeing with you but we end up in
>>> agreement.
>>> 
>>>> On 29/01/2015 19:05, Annette Greiner wrote:
>>>> 
>>>> I think I know why this is so difficult.
>>>> The problem, I think, is that we are putting normative information
>>>> into a section that is about outcomes.
>>> 
>>> 
>>> Hmm... sorry Annette, I think it's the right place for it.
>>> 
>>> The purpose of normative information in a best practice document is to
>>> tell the readers what they ought to be doing, what actions they should
>>> be taking or not taking.
>>> 
>>> Well, we could do that but then we're being more prescriptive than we
>>> need to be and, at the same time, limiting our audience. If we were to
>>> say something like "you must use DCAT" then we lock out people who
>>> prefer the alternatives (schema.org, ADMS, CKAN-native and more). The
>>> more general statement (in BP Provide Metadata) is:
>>> 
>>> It MUST be possible for data consumers to:
>>> - discover the data;
>>> - understand the nature and structure of the data,
>>>   i.e. what the data describes and how it does it;
>>> - find out the origin of the data and under what terms it may be used.
>>> 
>>> and then we give more specific advice but it leaves the door open to
>>> different implementations that achieve the same goal.
>>> 
>>> 
>>> 
>>>  The purpose of a description of an intended outcome is to describe the
>>> result of taking that action. So we are stuck trying to describe both
>>> the thing to do and its result in one go.
>>> 
>>> I don't think so. The result is normative, the how to do it is not.
>>> 
>>>> 
>>>> If we rewrite all the intended outcomes to become descriptions of the
>>>> actions to take, they will end up reading an awful lot like what we
>>>> have for subtitles right now, which will be redundant at best and
>>>> contradictory at worst.
>>> 
>>> 
>>> I agree with that.
>>> 
>>>  We would also have to rename that piece of the template from "intended
>>> outcome" to something that makes more sense. If we keep the intended
>>> outcomes as outcomes, we could choose to put all the normative
>>> information into the subtitles and beef each of those up into something
>>> more like a synopsis, which is what they are already approaching.
>>> 
>>> I wouldn't oppose that.
>>> 
>>>  I think having only one place where we put the normative text would
>>> simplify usability of the document.
>>> 
>>> I am happy with that. In my original suggestion, the Intended outcome
>>> was the normative statement but the editors added the keywords to the
>>> subtitle. I'd be happy to follow your suggestion.
>>> 
>>>> 
>>>> (And yes, I think that this mismatch is a problem with the SharePSI
>>>> document that ours was modeled on.)
>>> 
>>> 
>>> Other way round (Share-PSI follows DWBP) but, OK, I take the point.
>>> 
>>> 
>>> Phil.
>>> 
>>>> -Annette
>>>> 
>>>> --
>>>> Annette Greiner
>>>> NERSC Data and Analytics Services
>>>> Lawrence Berkeley National Laboratory
>>>> 510-495-2935
>>>> 
>>>> On Jan 28, 2015, at 2:35 PM, Bernadette Farias Lóscio
>>>> <bfl@cin.ufpe.br> wrote:
>>>> 
>>>>> Hi all,
>>>>> 
>>>>> We have made some changes [1] related RFC 2119 in some Best Practices
>>>>> specifically in the Intended Outcome section. However, there are two
>>>>> BPs, BP#6 [2] and BP#32 [3] that we couldn’t change and we kindly ask
>>>>> for the contributors to review them considering Phil’s explanation.
>>>>> 
>>>>> Thanks!
>>>>> Bernadette, Caroline and Newton
>>>>> 
>>>>> [1]
>>>>> 
>>>>> https://github.com/w3c/dwbp/commit/532f4ce7dbdf63ebf70fe90a776364d607b2bc19
>>>>> 
>>>>> [2] http://w3c.github.io/dwbp/bp.html#LocaleParametersMetadata
>>>>> [3] http://w3c.github.io/dwbp/bp.html#resourcestatus
>>>>> 
>>>>> 2015-01-28 16:11 GMT-03:00 Phil Archer <phila@w3.org>:
>>>>>> 
>>>>>> I meant to say... see the License BP at
>>>>>> 
>>>>>> 
>>>>>> https://github.com/w3c/dwbp/commit/5b764095b4f39c24e8c91ece4e35bb72df04146a
>>>>>> 
>>>>>> 
>>>>>> from around line 1386. That's one of the BPs I changed most.
>>>>>> 
>>>>>> HTH
>>>>>> 
>>>>>> Phil
>>>>>> 
>>>>>> 
>>>>>>> On 28/01/2015 19:08, Phil Archer wrote:
>>>>>>> 
>>>>>>> 
>>>>>>> Thanks Eric,
>>>>>>> 
>>>>>>> The BP template [1] is the basic guide. Key things I'd say:
>>>>>>> 
>>>>>>> In the Why section, remember the first two axiomatic questions:
>>>>>>> 
>>>>>>> Why this is unique to publishing or re-using data on the Web?
>>>>>>> How does this encourages publication or re-use of data on the Web?
>>>>>>> 
>>>>>>> These can be answered in prose rather than bullet points but they
>>>>>>> get to
>>>>>>> heart of the problem the BP solves.
>>>>>>> 
>>>>>>> Then the Intended Outcome. This is the normative bit, i.e. what we can
>>>>>>> judge an implementation to have done or not. MUST is very strong,
>>>>>>> SHOULD
>>>>>>> essentially means "comply or explain" (and your explanation for not
>>>>>>> doing so better be good). There is also MUST NOT, SHOULD NOT etc.
>>>>>>> available.
>>>>>>> 
>>>>>>> And we should avoiding telling humans what they SHOULD do. We can,
>>>>>>> however, tell publishers what they SHOULD do in order to meet the
>>>>>>> needs
>>>>>>> of humans.
>>>>>>> 
>>>>>>> Possible approach to implementation is where we offer help but it
>>>>>>> needs
>>>>>>> to be quite generic, perhaps pointing to other resources, multiple
>>>>>>> ways
>>>>>>> of achieving the intended outcome etc. There certainly shouldn't be
>>>>>>> any
>>>>>>> SHOULDs or MUSTs here.
>>>>>>> 
>>>>>>> How to test - ideally the outcome is binary, pass/fail. Some BPs have
>>>>>>> included things like "download the dataset, write a script..." I don't
>>>>>>> agree with that approach. You're testing against the intended outcome.
>>>>>>> Ideally the test can be machine-tested but even for humans, the test
>>>>>>> must be deterministic.
>>>>>>> 
>>>>>>> I'll try and spend more time on it tomorrow, Thursday.
>>>>>>> 
>>>>>>> Thanks Eric as always
>>>>>>> 
>>>>>>> Phil.
>>>>>>> 
>>>>>>> 
>>>>>>> [1] http://w3c.github.io/dwbp/bp.html#bp-template
>>>>>>> [2]
>>>>>>> 
>>>>>>> 
>>>>>>> https://github.com/w3c/dwbp/commit/5b764095b4f39c24e8c91ece4e35bb72df04146a
>>>>>>> 
>>>>>>> 
>>>>>>>> On 28/01/2015 16:39, Eric Stephan wrote:
>>>>>>>> 
>>>>>>>> 
>>>>>>>> Phil and editors,
>>>>>>>> 
>>>>>>>> I'm slammed today (Wednesday morning here) with a project, if all
>>>>>>>> goes
>>>>>>>> well
>>>>>>>> I can help tomorrow.
>>>>>>>> 
>>>>>>>> To save some time, what might be helpful if an editor could help give
>>>>>>>> some
>>>>>>>> specific guidance make an association that BP # (from the set of
>>>>>>>> 22-33)....
>>>>>>>> should read like BP #(from the set of 1-21).  It was helpful for
>>>>>>>> instance
>>>>>>>> referencing the Metadata best practice when I wrote the Provenance
>>>>>>>> best
>>>>>>>> practice.
>>>>>>>> 
>>>>>>>> Thanks,
>>>>>>>> 
>>>>>>>> Eric S.
>>>>>>>> 
>>>>>>>>> On Tue, Jan 27, 2015 at 12:52 PM, Phil Archer <phila@w3.org> wrote:
>>>>>>>>> 
>>>>>>>>> Hi all,
>>>>>>>>> 
>>>>>>>>> I've been preparing the BP doc for its FPWD publication - a task
>>>>>>>>> that I
>>>>>>>>> have not yet completed as, I'm sorry to say, there is still quite
>>>>>>>>> a lot
>>>>>>>>> more to do and what I have done has taken a lot longer than I
>>>>>>>>> anticipated.
>>>>>>>>> 
>>>>>>>>> I've been focused on a couple of issues.
>>>>>>>>> 
>>>>>>>>> First, several BPs included RFC 2119 keywords in the possible
>>>>>>>>> implementation section and/or the why section. The BP template
>>>>>>>>> states
>>>>>>>>> that
>>>>>>>>> the Intended Outcome is normative - that's where MUST, SHOULD,
>>>>>>>>> SHOULD
>>>>>>>>> NOT
>>>>>>>>> etc. belong. They are repeated in the short description
>>>>>>>>> underneath the
>>>>>>>>> title but not elsewhere.
>>>>>>>>> 
>>>>>>>>> In other words, some writers have evidently been a little
>>>>>>>>> confused about
>>>>>>>>> the structure. In trying to create a more regular structure I have
>>>>>>>>> had to
>>>>>>>>> reorder the text a little but, as far as possible, have kept my own
>>>>>>>>> views
>>>>>>>>> out of it (I haven't always succeeded).
>>>>>>>>> 
>>>>>>>>> Taking out the RFC 2119 bits of the implementation sections has
>>>>>>>>> meant
>>>>>>>>> more
>>>>>>>>> than just removing emphasis, it's meant quite significant rewrites -
>>>>>>>>> more
>>>>>>>>> than I fee comfortable doing without WG review.
>>>>>>>>> 
>>>>>>>>> I keep in mind Antoine's point about writing BPs that say what
>>>>>>>>> humans
>>>>>>>>> MUST
>>>>>>>>> do - so I've made a few edits to say what publishers MUST do for the
>>>>>>>>> benefit of human users.
>>>>>>>>> 
>>>>>>>>> Some BPs needed more rewriting than others of course.
>>>>>>>>> 
>>>>>>>>> In doing this I have long missed the deadline for getting the
>>>>>>>>> document
>>>>>>>>> published today, and, as I say, I've made such changes that I feel I
>>>>>>>>> have
>>>>>>>>> gone beyond editorial changes and really feel we need another WG
>>>>>>>>> review
>>>>>>>>> before publishing.
>>>>>>>>> 
>>>>>>>>> So, at the risk of upsetting lots of people, I suggest:
>>>>>>>>> 
>>>>>>>>> - I will do my best to make more changes tomorrow (caveat, I have a
>>>>>>>>> meeting in London tomorrow so I'll mostly be doing this on train
>>>>>>>>> and may
>>>>>>>>> not finish).
>>>>>>>>> 
>>>>>>>>> - I encourage writers of BPs 1 - 21 to take a look at what I've
>>>>>>>>> changed
>>>>>>>>> and put back/ make any more changes you feel necessary.
>>>>>>>>> 
>>>>>>>>> - If you wrote any of BPs 22 - 33, please take a careful look at the
>>>>>>>>> structure of the earlier ones and see if you want to make any
>>>>>>>>> changes to
>>>>>>>>> your text.
>>>>>>>>> 
>>>>>>>>> - Editors - I've gone well beyond what I ought to do to your
>>>>>>>>> document
>>>>>>>>> here. I hope you don't mind.
>>>>>>>>> 
>>>>>>>>> - Chairs - sorry, I really think the WG needs to look again and vote
>>>>>>>>> again
>>>>>>>>> on Friday.
>>>>>>>>> 
>>>>>>>>> Again, I hope I haven't upset anyone here, but reading through
>>>>>>>>> the doc
>>>>>>>>> line by line I have felt significant changes were necessary.
>>>>>>>>> 
>>>>>>>>> Phil.
>>>>>>>>> 
>>>>>>>>> --
>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> Phil Archer
>>>>>>>>> W3C Data Activity Lead
>>>>>>>>> http://www.w3.org/2013/data/
>>>>>>>>> 
>>>>>>>>> http://philarcher.org
>>>>>>>>> +44 (0)7887 767755
>>>>>>>>> @philarcher1
>>>>>> 
>>>>>> --
>>>>>> 
>>>>>> 
>>>>>> Phil Archer
>>>>>> W3C Data Activity Lead
>>>>>> http://www.w3.org/2013/data/
>>>>>> 
>>>>>> http://philarcher.org
>>>>>> +44 (0)7887 767755
>>>>>> @philarcher1
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> --
>>>>> Bernadette Farias Lóscio
>>>>> Centro de Informática
>>>>> Universidade Federal de Pernambuco - UFPE, Brazil
>>>>> 
>>>>> ----------------------------------------------------------------------------
>> 
>> --
>> 
>> 
>> Phil Archer
>> W3C Data Activity Lead
>> http://www.w3.org/2013/data/
>> 
>> http://philarcher.org
>> +44 (0)7887 767755
>> @philarcher1
> 
> 
> 
> -- 
> Bernadette Farias Lóscio
> Centro de Informática
> Universidade Federal de Pernambuco - UFPE, Brazil
> ----------------------------------------------------------------------------
>

Received on Wednesday, 4 February 2015 13:45:46 UTC