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

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