Re: dwbp-ISSUE-244: Replacing sections Data on the Web Challenges and BP Benefits [Best practices document(s)]

Hello Annette,

2016-03-10 19:30 GMT-03:00 Annette Greiner <amgreiner@lbl.gov>:

> Sorry to say, but I disagree. We decided to move them because they
> amounted to three different tables of contents, which is awkward in any
> document. The challenges and the benefits could serve equally well as
> indexes, so I think it makes sense to have them at the end. I do see the
> value in introducing them in some way before using them in the BPs. I
> wouldn't mind adding a sentence in the introduction introducing the
> circular symbols and linking to the benefits index.
>

Thanks for your message and suggestions! I know the group decided to move
the two sections to the end of the document, but I wasn't on the call when
this was voted.  I just raised this issue because I think that we miss some
explanations with the current organization. IMO these explanations are
important to understand the document.

I am ok with removing the diagram about BP x Benefits and I also agree that
we don't need a whole section to explain the benefits. We can just add an
explanation about the benefits in the introduction.

 <rant>

> In general, though, I would like to cut down on front matter and back
> matter so the BPs themselves are a higher percentage of the content of the
> document. As it is, it takes the reader a long time to reach the meat of
> the document, and I think the surrounding text reads like a bit too much
> puffery.


> Here are some things we could do. We could pull the row of benefits
> symbols out of the template, use them in the introduction next to the ONE
> sentence about them, and toss the template itself. (Why do we even have the
> template in there? It was helpful for us, but it just takes up space now. I
> don't think readers need it.) Also, the last two paragraphs in section 4
> seem unnecessary. They focus on specific BPs, which are described in the
> list of BPs already (as they should be). I see no reason to call out those
> specific ones in particular. I also find the diagram in section 4 more
> confusing than enlightening. Why is metadata shown as separate from the
> individual distributions on the left and a different list of metadata is
> shown within each distribution on the right? What are we trying to say with
> that diagram?
>
>  I think we could cut some of the back matter as well. For instance,
> section 11 is redundant with section 10. Does section 12 need to be there,
> or could we just link to the use case doc? The challenges section seems to
> me good that we thought about it, but I doubt its utility for readers. The
> challenges diagram is unreadable without zooming in multiple times, and I
> don't think it adds anything to the doc, as it just reiterates the
> contents. The text in that section could be one sentence in the
> introduction to section 6. Oh, wait, that's already in there at the
> beginning of section 6. Great! Let's leave it at that and remove section 9.
>

I don't think that we should make so many changes on the document.

I don't agree with removing the template. I think it is important to
describe the structure of the BP before presenting them. It is important to
describe the meaning of each part of the BP. Other BP documents have
something similar [1].

The diagram of Section 4 was presented during our last F2F and the group
didn't complain about it. I don't agree with you that it is confusing. The
last paragraph of Section 3 explains the diagram. If you don't agree with
the explanation then maybe you can improve it.

I don't agree that we need "to cut down on front matter and back matter".
If the reader  knows everything about publishing data on the Web and he is
interested just on the BP, then he can go directly to Section 7. We also
have a table of contents on the left side to facilitate the navigation.

Section 12 [2] and Section 13 [3] may also be removed, but I don't see a
problem with having them, specially because they are at the end of the
document and they are just informative (they present an overview about the
relationship between BP and Benefits, and BP and Requirements).

The size of the challenges diagram was ok before the ReSpec change. I agree
that now it is too small. I suggested to bring this section to the front
because it explains the idea behind the structure of the document. But, I
am also ok with changing the introduction of Section 7 to explain this.
However, I don't agree with removing the diagram. It can stay at the end of
the document and we can link to it.

kind regards,
Bernadette

[1] https://www.w3.org/TR/mobile-bp/#bpstructure
[2] http://w3c.github.io/dwbp/bp.html#BP_Benefits
[3] http://w3c.github.io/dwbp/bp.html#requirements





> </rant>
> -Annette
>
>
>
> On 3/10/16 12:49 PM, Data on the Web Best Practices Working Group Issue
> Tracker wrote:
>
>> dwbp-ISSUE-244: Replacing sections Data on the Web Challenges and BP
>> Benefits [Best practices document(s)]
>>
>> http://www.w3.org/2013/dwbp/track/issues/244
>>
>> Raised by: Bernadette Farias Loscio
>> On product: Best practices document(s)
>>
>>
>> I'd like to propose to bring the section Data on the Web Challenges to
>> its original place [1]. I think it is important this section appears before
>> the BP because this section explains how the development of Data on the Web
>> Best Practices was guided by the UC requirements. Besides, the organization
>> of the document is based on the challenges described in the diagram. So, it
>> is really a waste to place this section at the end of the document. If
>> necessary, the title of the section may be changed to "Document
>> Organization" or something similar.
>>
>> In a similar way, the section Best Practices Benefits should be placed
>> before the BP. I think it is important to explain each one of the benefits
>> before presenting the BP. I propose to bring the section to its original
>> place without the diagram (index of BP according to Benefits). The diagram
>> may be part of the Section Best Practices x Benefits.
>>
>>
>>
>>
> --
> Annette Greiner
> NERSC Data and Analytics Services
> Lawrence Berkeley National Laboratory
>
>
>


-- 
Bernadette Farias Lóscio
Centro de Informática
Universidade Federal de Pernambuco - UFPE, Brazil
----------------------------------------------------------------------------