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

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