W3C home > Mailing lists > Public > public-dwbp-wg@w3.org > March 2016

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

From: Annette Greiner <amgreiner@lbl.gov>
Date: Sun, 13 Mar 2016 11:55:35 -0700
Cc: "public-dwbp-wg@w3.org" <public-dwbp-wg@w3.org>
Message-Id: <224EDEC5-178F-42DC-AC70-8E4244A07864@lbl.gov>
To: Bernadette Farias Lóscio <bfl@cin.ufpe.br>
The idea was that we could get rid of the index that section 10 provides. The net increase in indexes would be zero. Adding a BP summary as you describe sounds like you are adding yet another index? I don't see how that addresses the issue of too many indexes. 
-Annette

Sent from a keyboard-challenged device

> On Mar 13, 2016, at 5:19 AM, Bernadette Farias Lóscio <bfl@cin.ufpe.br> wrote:
> 
> Hi Annette,
> 
> Thanks for your suggestion! I agree with you. However, we just made a test including the BP in the table of contents and the result was not good. If we do this then we're gonna have another "index" associated to each BP. To solve the problem that you mentioned,  we're planning to provide a BP summary that allows the reader to filter BP by challenge or by benefit. We can also add some keywords (ex: API, bulk,...) to each challenge to clarify the meaning of each challenge. 
> 
> Cheers,
> Bernadette
> 
> 
> 
> 2016-03-11 20:29 GMT+01:00 Annette Greiner <amgreiner@lbl.gov>:
>> Hey, I have an idea how we can make us of the content in the diagram from section 10. We could put the names of the BPs into the sidebar, so they would show up below their respective "challenges" there. This would solve two other problems. Namely, that it's difficult to find a given BP from the middle of the doc (I keep experiencing this, and I imagine new readers will do even more so), and that certain topics appear not to be covered because the name of their "challenge" doesn't strongly suggest them. (I think many people would think we had nothing to say about APIs because the word never shows up in that sidebar.)
>> -Annette
>> 
>>> On 3/10/16 6:13 PM, Bernadette Farias Lóscio wrote:
>> 
>>> 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
>>> ----------------------------------------------------------------------------
>> 
>> -- 
>> 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
> ----------------------------------------------------------------------------
Received on Sunday, 13 March 2016 18:56:09 UTC

This archive was generated by hypermail 2.3.1 : Sunday, 13 March 2016 18:56:09 UTC