Re: Working on FPWD, more to do

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 Tuesday, 3 February 2015 22:55:05 UTC