Re: Review of FPWD Conneg-by-ap

I have a significant number of editorial comments for the document -
many more than I would be able to write up and send in an email. I'm
wondering if it would make sense to fork a copy of the document where we
can put comments and suggestions but that wouldn't interfere with the
visible public draft. That would make it possible to do messy things
like add comments in the midst of text. Or do folks have other
suggestions for a best way to do this?

kc

On 11/12/18 6:00 PM, Car, Nicholas (L&W, Dutton Park) wrote:
> Agree, thanks Antoine, really useful edits. Will work with Rob to
> incorporate all and will create Issues/Pulls as appropriate to track
> progress referring to your numbers below.
> 
>  
> 
> Nick
> 
>  
> 
>  
> 
> *From:*Rob Atkinson <rob@metalinkage.com.au>
> *Sent:* Tuesday, 13 November 2018 10:22 AM
> *To:* Antoine Isaac <aisaac@few.vu.nl>
> *Cc:* Dataset Exchange Working Group <public-dxwg-wg@w3.org>
> *Subject:* Re: Review of FPWD Conneg-by-ap
> 
>  
> 
>  
> 
> Thanks Antoine
> 
>  
> 
> this is great feedback - I dont see any fundamental disagreements but a
> lot of very constructive suggestions for improving text. 
> 
>  
> 
> I'll wait for plenary decisions tomorrow but FWIW I am willing to do an
> editorial job to try to incorporate as much as I feel confident i can
> improve and make sure issues are in place where something more
> substantive is needed.  Or let someone else do this :-)
> 
>  
> 
> Rob
> 
>  
> 
>  
> 
>  
> 
>  
> 
>  
> 
> On Tue, 13 Nov 2018 at 08:37, Antoine Isaac <aisaac@few.vu.nl
> <mailto:aisaac@few.vu.nl>> wrote:
> 
>     Dear Conneg-by-ap editors, all,
> 
>     As requested I've read https://w3c.github.io/dxwg/conneg-by-ap/
>     (FPWD, dated November 8 2018).
>     Here's a quick review of it.
> 
>     The summary: the document reads quite well (until the Appendices)
>     and I don't see a major blocker. Honestly I feel uneasy about moving
>     into FPWD a document for which major parts did not exist at the last
>     F2F, 3 weeks ago. And there are some bits (especially for the QSA)
>     that seem could have matured more before being included. Some of my
>     issues are not editorial... But, in accordance with the mantra of
>     publishing often, I clearly don't feel like objecting to this FPWD
>     publication.
>     The level of quality seems high enough, even if I hope you can
>     address some of my comments before releasing it ;-)
> 
>     My comments follow below. I have not created github issues, partly
>     because I didn't have the time and partly because there might
>     already be issues created for these issues (there was at least one,
>     which I've re-opened).
>     I've tried to number my comments in case one wants to refer to them
>     in later emails. They sometimes align with section numbers, but it's
>     not on purpose :-)
> 
>     Note that there is one matter which I think should stand out: it's
>     #15, on compatibility with Linked Data conneg.
> 
>     I hope this helps,
> 
>     Antoine
> 
>     =============
> 
>     1. Abstract
>     The two last paragraphs ("For details about what a profile is, see
>     the [PROF-GUIDE] [...]" and "For the formal ontology describing
>     profiles, [...]") are clearly not abstract-level material.
> 
>     2. Introduction (section 1)
>     "Thus, resources available in different languages" wrongly uses
>     "thus". There's no direct logical implication between Media Type
>     considerations and Language ones.
> 
>     3. Motivation (3)
>     To me this section could be merged with the introduction. There's
>     quite a bit of overlap, and I think putting the motivation early in
>     documents always help.
>     I've re-opened https://github.com/w3c/dxwg/issues/379
> 
>     4. Related Work content (4)
>     "What a profile is and how to create one is detailed in the
>     [PROF-GUIDE] document [...]",
>     "Issue 380: Remove text in favour of full reference to final IETF
>     doc [...]" and
>     "Describing the parts of profiles and their relation to other
>     profiles is done within the Profiles Ontology"
>     are not related work material to me. They're rather about explaining
>     our current (pieces of) work, and therefore seem a better fit for
>     the intro.
> 
>     5. Abstract Model/Context (5.1)
>     The paragraph that includes "For this reason, other than a directive
>     to maintain independence, no further discussion of negotiation by
>     profile and this relations to other forms of negotiation are given"
>     reads strange in the flow of other paragraphs. It doesn't read like
>     context, in fact.
> 
>     6. Abstract Model/Context (5.1)
>     The paragraph starting with "A client requesting the representation
>     of a resource conforming to a profile MUST identify the resource"
>     clearly doesn't read like a piece of context, as it gives normative
>     instructions.
> 
>     7. Abstract Model/Context (5.1)
>     The sentence "In this abstract model, we don't assume any specifics
>     about client, server, resource, metadata, request or response" reads
>     strange as definitions have been given earlier about these notions.
>     So there is a form of assumption going on.
> 
>     8. Abstract Model/Requests and Responses (5.2)
>     I don't get why there's such a long introduction to 5.2. Not only
>     this is long, but it results in splitting information that would be
>     easier to understand if it was kept together in each of the
>     subsections. For example it's strange to have 5.2.2 not saying what
>     the server should do (this info is only in the intro).
> 
>     9. Abstract Model/Requests and Responses (5.2)
>     "a server responds the list of profile tokens it is able to deliver
>     resource representations conforming to and their mapping to profile
>     URIs" is quite hard a sentence to swallow. Maybe adding a bit of
>     punctuation and/or a conjunction would help.
> 
>     10. Abstract Model/Requests and Response (5.2.1)
>     "The list profiles request MAY be an independent request or part of
>     another realization's request". I'm not sure this requires such
>     emphasis (the 'MAY'); it doesn't strike me as spec-level, compared
>     to the paragraph just after.
> 
>     11. Abstract Model/preferences (5.2 and 6.1)
>     5.2.2 mentions that preferences are expressed in 'some form of list
>     ordering'. This is a bit different from the quality indicators from
>     6.1.2. And (a question real question at the same time as a possible
>     example of issue:) can q values have ties?
> 
>     12. Abstract Model/tokens (5.2.3)
>     Typo on 'refere'.
> 
>     13. HTTP intro (6.1)
>     "namely media type (Accept/Content-Type), encoding
>     (Accept-Encoding/Content-Encoding) and language
>     (Accept-Language/Content-Language)" could be in the introduction
>     instead (where these precise formulations of the 'other' accept
>     headers are not quite there.
> 
>     14. HTTP OPTIONS (6.1.1)
>     It is strange to find this section first in 6.1 while (according to
>     the wording of issue 510) OPTIONS is not recommended practice.
> 
>     15. Compatibility of examples with Linked Data conneg (6.1.1 and 6.1.2)
>     Examples 2 and 3 are at odds with the conneg recipes derived from
>     Http-range-14. In RDF statements, the 'most interesting' URIs are
>     URIs of non-information resources. These non-information resources
>     are expected to first be de-referenced to the URI of a
>     representation via a 303-redirect. That URI is then served with a 200.
>     There are of course cases where the pattern of examples 2 and 3 will
>     be the right one. But now the text really says that the simple 200
>     pattern is the one expected ("a request/response pair would look as
>     follows").
>     At least, there should be a prominent note/issue saying that there
>     are other content negotiation patterns. Ideally, an example with
>     303-redirect would be introduced - or perhaps even replace the
>     simple 200 one.
> 
>     16. QSA - motivation (6.2)
>     In the end, QSA requires a lot of rather subtle instructions and
>     text, but there is little motivation for it in the draft. I'm ready
>     to accept that we have some cases and requirements somewhere, but
>     they are not rendered. Or if they are, they should be more
>     prominently advertised, as I've missed them :-/ .
> 
>     17. QSA - level of specification (6.2)
>     The wording around what the draft recommends on QSA is quite confusing.
>     In the intro of 6.2 the sentence
>     "this realization is fully specified here and this document is
>     considered normative for the QSA realization."
>     seems to contradict the one that follows it:
>     "This realization does not preclude other QSA specifications for
>     profile and content negotiation"
>     I think I understand where the draft wants to go, in fact. But then
>     I really feel uneasy when I read rather strong recommendations like
>     "The QSA key/value pair _profile=list SHOULD be used" in 6.2.1.
> 
>     18. QSA - mention of mediatype (6.2)
>     "In this realization, _profile and _mediatype are used to
>     indicate[...]" hints that media type is a key aspect of the
>     realization. I guess it's not. I mean, I'm not sure why a spec about
>     getting profile-specific representation would blur the picture by
>     also discussing media types quite extensively.
> 
>     19. QSA - example 7
>     I'm struggling to see why example 7 ("GET
>     /a/resource?_profile=aaa,bbb,ccc HTTP/1.1") is about "Requesting a
>     list of profiles for a resource by QSA in HTML"
> 

-- 
Karen Coyle
kcoyle@kcoyle.net http://kcoyle.net
m: 1-510-435-8234 (Signal)
skype: kcoylenet/+1-510-984-3600

Received on Tuesday, 13 November 2018 03:08:47 UTC