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

I don't think having a table of contents is a good excuse for having an 
unwieldy document or maintaining content that doesn't add value. If we 
can improve the doc, we should. Also, I think suggestions for 
improvement should be taken on their merits unless they've been 
previously voted down. I could possibly improve the diagram or its 
description, but that would require having some clue as to what it was 
meant to convey.
-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