Re: Working on FPWD, more to do

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

Received on Friday, 30 January 2015 13:12:13 UTC