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

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.

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

Received on Thursday, 10 March 2016 22:30:57 UTC