- From: Car, Nicholas (L&W, Dutton Park) <Nicholas.Car@csiro.au>
- Date: Tue, 13 Nov 2018 03:43:11 +0000
- To: "kcoyle@kcoyle.net" <kcoyle@kcoyle.net>
- CC: "public-dxwg-wg@w3.org" <public-dxwg-wg@w3.org>
- Message-ID: <FF5DF933-7ACF-4A2B-9676-5DFE4CA12C87@csiro.au>
Hi Karen,
Yes, please just branch the doc and apply edits to the branch. We won’t merge that branch into the public copy while a FPWD is frozen but we can all treat the branch/branches as live and keep pushing to it/them.
I will add Antoine’s email edits to such a branch ASAP.
Thanks,
Nick
Nicholas Car
Senior Experimental Scientist
CSIRO Land & Water
E nicholas.car@csiro.au<mailto:nicholas.car@csiro.au> M 0477 560 177<tel:0477%20560%20177> P 07 3833 5632
Dutton Park, QLD, Australia
On 13 Nov 2018, at 1:10 pm, Karen Coyle <kcoyle@kcoyle.net<mailto:kcoyle@kcoyle.net>> wrote:
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<mailto:rob@metalinkage.com.au>>
*Sent:* Tuesday, 13 November 2018 10:22 AM
*To:* Antoine Isaac <aisaac@few.vu.nl<mailto:aisaac@few.vu.nl>>
*Cc:* Dataset Exchange Working Group <public-dxwg-wg@w3.org<mailto: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>
<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<mailto: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:43:44 UTC