W3C home > Mailing lists > Public > public-dwbp-wg@w3.org > January 2015

Re: Working on FPWD, more to do

From: Phil Archer <phila@w3.org>
Date: Thu, 29 Jan 2015 21:51:02 +0000
Message-ID: <54CAAB46.3070905@w3.org>
To: Annette Greiner <amgreiner@lbl.gov>, Bernadette Farias Lóscio <bfl@cin.ufpe.br>
CC: Eric Stephan <ericphb@gmail.com>, Newton Calegari <newton@nic.br>, Caroline Burle <cburle@nic.br>, Public DWBP WG <public-dwbp-wg@w3.org>
Thanks for this Annette,

In my comments below I begin by disagreeing with you but we end up in 

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.


> -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

+44 (0)7887 767755
Received on Thursday, 29 January 2015 21:50:25 UTC

This archive was generated by hypermail 2.3.1 : Thursday, 29 January 2015 21:50:25 UTC