Re: [dxwg] Antoine's conneg doc edits (#575)

I've just tried to assess where we stand here... The numbers refer to @aisaac's original numbering.

Number | Antoine's original question | My comment (also referring to [Antoine's last comment](https://github.com/w3c/dxwg/issues/575#issuecomment-440056620)
---------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------
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. | OK
 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. | OK (resolved through #598)
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 #379 | OK
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 | The   text about "what a profile is …" is not in the document any more, so I'd say we can consider this point addressed
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. | Still open; should be addressed through a re-write of section 6.1
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. | Still open; should be addressed through a re-write of section 6.1, putting this text in 6.2
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. | Still open; should be addressed through a re-write of section 6.1
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). | OK
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. | OK
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. | Still open; Antoine considers the use of RFC 2119 language inappropriate
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? | Could be resolved by referencing #591 in the document
12 | Abstract Model/tokens (5.2.3) Abstract Model/tokens (5.2.3) | OK
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. | OK
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. | Should be OK since #510 has been closed
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"). | Could be OK, even though Antoine said that "it raised another question"
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 :-/. | This comment has not yet been addressed
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. | This comment has not yet been addressed
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. | This comment has not yet been addressed
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" | This comment has not yet been addressed

Antoine, does that reflect your view, too?


-- 
GitHub Notification of comment by larsgsvensson
Please view or discuss this issue at https://github.com/w3c/dxwg/issues/575#issuecomment-480702667 using your GitHub account

Received on Monday, 8 April 2019 06:36:56 UTC