Re: Working on FPWD, more to do

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

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. 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 think having only one place where we put the normative text would simplify usability of the document. 

(And yes, I think that this mismatch is a problem with the SharePSI document that ours was modeled on.)
-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
> ----------------------------------------------------------------------------
>

Received on Thursday, 29 January 2015 19:06:30 UTC