search

w3c / WebID

https://www.w3.org/groups/cg/webid
MIT License
14 stars 7 forks source link

Terminology: WebID Profile #4

Closed acoburn closed 2 years ago

acoburn commented 2 years ago

The current draft specification includes, in the Terminology section, a definition of a WebID Profile:

WebID Profile or Profile Document A WebID Profile is an RDF document which uniquely describes the Agent denoted by the WebID in relation to that WebID. The server must provide a text/turtle [turtle] representation of the requested profile. This document may be available in other RDF serialization formats, such as RDFa [RDFA-CORE], or [RDF-SYNTAX-GRAMMAR] if so requested through content negotiation.

Even the terminology uses two names for this entity: "WebID Profile" or "Profile Document", and throughout the draft specification, this entity is referred to, variously, as:

If a single phrase were used to denote this entity, there would be several advantages: first, the text of the draft specification would be more consistent; second, other documents (e.g., external specifications) could be much more precise when referring to or refining the notion of a WebID Profile Document.

I have no particular preference about the phrase that is chosen to describe this entity, just that it be consistent.

jacoscaz commented 2 years ago

Good point @acoburn . I myself prefer WebID Profile Document and I can accept Profile Document. Anything that doesn't contain Document isn't explicit enough IMHO.

TallTed commented 2 years ago

@csarven @bblfish —

https://github.com/w3c/WebID/commit/48f571868c7cb5d5612e48a3eae6342ce85b0983 and https://github.com/w3c/WebID/commit/c3e40307a1f74e8b9aa376f58d8c0e2c5fe43fc7 should have been put through the normal PR process, even if it were a second PR doing the same thing as #8 has failed to (entirely) do.

Having not done so left lines 537, 539, and 705 referring to the document, and line 706 referring to the WebID document, where all should instead refer to the WebID Profile Document.

https://github.com/w3c/WebID/pull/13 fixes those 4 lines (plus one instance of the document which is better as this document)

csarven commented 2 years ago

I'm not aware of any "normal PR process" guaranteeing work that's sound, complete, let alone unanimity.

PR 8 made significant improvements based on the need in this issue. What additional ceremony, discussions, reviews, or "process" is expected for a PR open for 6 months at this point on the 11th hour? The suggestions you're making now could've been done much earlier - not to imply that they're not appreciated. If something - which is fairly subjective in some cases - wasn't part of an original PR, I don't see that as an issue or something to be pedantic about or a blocker. We can move on by removing friction as reasonably as possible and then follow up with new updates.

Our goal was to be consistent with terminology and clarify context. That does not entail that every "the document" needs to be replaced with "the WebID Profile Document". This is very editorial. To take an example, in https://github.com/w3c/WebID/commit/c3e40307a1f74e8b9aa376f58d8c0e2c5fe43fc7#diff-e71370fe4d6679f0e463b9635a1270db4399459e10231e8e9c471976b4641b5eR537 , you're recommending "denotes the document describing" changed to "denotes the WebID Profile Document describing", i.e.:

The WebID Profile Document URI - "http://www.w3.org/People/Berners-Lee/card" (without the #i hash tag) - denotes the document describing the person (or more generally any agent) who is the referent of the WebID URI.

to

The WebID Profile Document URI - "http://www.w3.org/People/Berners-Lee/card" (without the #i hash tag) - denotes the WebID Profile Document describing the person (or more generally any agent) who is the referent of the WebID URI.

I don't actually agree that change is necessary. The context of "the document" is sufficiently clear and readable (to me). Had that suggestion was made in the PR, I wouldn't have necessarily raised an objection against it either. If it was so pressing, it could've been raised any time within the past 6 months.

bblfish commented 2 years ago

I agree that we also need to take into account the readability of the text, and too much repetition will make the text unreadable. This is for the same reason that Turtle is much more readable to a human than NTriples is. :-)

TallTed commented 2 years ago

(@bblfish — tangent... As I have understood it, the avoidance of repetition in Turtle, through the use of ; and ,, was more to favor human authors than human readers. Of course, the inconsistent handling of the empty ;. vs ,;. vs ,. sequences that are found in some human-authored Turtle — and even in some software-authored Turtle, as that software itself was human-authored — has helped neither authors not readers, and may be addressed in a contemplated next revision of Turtle.)

My suggested additional WebID Profile Document changes are aimed in part at increasing comprehensibility for readers with English as a second (or third, etc.) language, for whom the context of document may not be sufficiently clear.