- From: Karen Coyle <kcoyle@kcoyle.net>
- Date: Tue, 13 Nov 2018 07:25:23 -0800
- To: public-dxwg-wg@w3.org
The comments that I have are just that: comments. I often do not have a
modification that I can make. This is one of the beefs I have with
github - it's designed for changes to code, not for comments on texts.
I'm very open to suggestions on how best to do this.
kc
On 11/12/18 9:00 PM, Rob Atkinson wrote:
> either a fork or branch gets messy to push new PR if it is full of
> comments too. Create a branch and provide small PRs by preference that
> are easy to review and accept completely. Lets talk tomorrow about
> process, I'm happy to either push to include or hold of on changes post
> FPWD as the content in the docs have been largely available for this
> sort review for a long time, but nothing like a deadline to get things
> happening :-)
>
> On Tue, 13 Nov 2018 at 14:43, Car, Nicholas (L&W, Dutton Park)
> <Nicholas.Car@csiro.au> wrote:
>
> 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
>>
--
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 15:25:54 UTC