Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Drop "family of documents" section from conneg #1105

Open
kcoyle opened this issue Sep 29, 2019 · 14 comments
Open

Drop "family of documents" section from conneg #1105

kcoyle opened this issue Sep 29, 2019 · 14 comments

Comments

@kcoyle
Copy link
Contributor

@kcoyle kcoyle commented Sep 29, 2019

The "DXWG family of documents" section in Conneg should be removed because:

  1. The documents do not make up a "family" because there is no direct relationship or dependency between them
  2. The way that most groups handle this is that the home page for the group lists the documents created by the group, including working group notes
  3. The IETF document is related to Conneg but is not a DXWG output. It should be listed in the Conneg document as a "sibling" document to Conneg.

We do need to consider what we want on the working group's home page at the end of this charter, and we can have it be a round-up of finished and ongoing work of the group.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 29, 2019

I disagree with 1. There are (and will be more once the Guidance is here) cross-references between our documents. And they will nicely complement each other, in the end.

I also disagree with 2. See for example:
https://www.w3.org/TR/prov-o/
https://www.w3.org/TR/2013/REC-sparql11-query-20130321/
And even the W3C spec which don't have a 'family' section formalized spend some time in the intro for citing other documents of that are related, explaining that the different roles are. Cf the OWL specs.

For 3 you are right, but we still can say that it belongs to a family. It's actually easier to present a family in a specific document where editors present their related work in different spaces, rather than on a W3C group page where it may be more awkward to list documents from other spaces.

Finally there's one big motivation. We have the section now, and it's very decent, so it will be much less work to adapt it answer specific comments you have (such as making sure the IETF document is not mistaken as an output from the WG) rather than to spend time for making up and discussing entire new paragraphs.

@kcoyle

This comment has been minimized.

Copy link
Contributor Author

@kcoyle kcoyle commented Sep 30, 2019

@aisaac As per 1, perhaps then there is a need to explain how it is that these documents relate to each other. Right now they are a listing of separate and separately named documents. That's far from the SPARQL example where all of the documents are in support of and part of SPARQL 1.1. It would make a difference to say how these documents support each other, because the way they are in Conneg right now they are all listed as emanating from DXWG but not presented as in support of each other. The document needs to say what is the unifying factor, and what are the dependencies, so people can know if they have to read all of them to understand any one of them. If there is no dependency then it should be made clear that they each stand alone. (Ranganathan's 4th law: Save the time of the reader.)

@nicholascar

This comment has been minimized.

Copy link
Contributor

@nicholascar nicholascar commented Sep 30, 2019

The model I used for the Family of Documents section is indeed PROV. This list all PROV WG outputs in all documents; Notes, Recs etc.

The document needs to say what is the unifying factor

Profiles?

and what are the dependencies

Minimal but as Guidance ramps up, it will be good to better link in references to it.

@larsgsvensson

This comment has been minimized.

Copy link
Contributor

@larsgsvensson larsgsvensson commented Sep 30, 2019

@aisaac scripsit:

For 3 you are right, but we still can say that it belongs to a family. It's actually easier to present a family in a specific document where editors present their related work in different spaces, rather than on a W3C group page where it may be more awkward to list documents from other spaces.

and

(such as making sure the IETF document is not mistaken as an output from the WG)

I'm a bit surprised over this comment, since you over at #575 (comment) wrote:

  1. It still holds! To me the IETF ID (and issue 380) is a PROF document, even if it's not in W3C space, and thus doesn't belong to related work. It is (y)our work.
@larsgsvensson

This comment has been minimized.

Copy link
Contributor

@larsgsvensson larsgsvensson commented Sep 30, 2019

@kcoyle scripsit:

The document needs to say what is the unifying factor, and what are the dependencies, so people can know if they have to read all of them to understand any one of them.

I guess that applies not only to conneg-by-ap but also to prof: and prof-guidance, too, in that case.

@nicholascar

This comment has been minimized.

Copy link
Contributor

@nicholascar nicholascar commented Sep 30, 2019

The document needs to say what is the unifying factor, and what are the dependencies, so people can know if they have to read all of them to understand any one of them.

The original intention of the 'family' was, and I see no reason why it shouldn't continue to be, that the documents are all aspects of profiles/profiling.

As per the bullet list in the FoD section, we have these sentences about each document:

  • [PROF] an RDF vocabulary that describes profiles and related resources
  • [PROF-CONNEG] specific guidance on how to negotiate for Internet resource content using profiles
  • [PROF-IETF] - Indicating and Negotiating Profiles in HTTP: an IETF Internet-Draft defining HTTP Headers for HTTP content negotiation by profile
  • The DXWG also plans to provide [PROF-GUIDANCE] - Profile Guidance: general recommendations and guidance on profiling.

I'd like to see the Guidance recommend that for formal profile descriptions, PROF be used and for mechanics for getting data according to profiles, CONNEG be used. PROF will happily make more references to Guidance about overall profile establishment, best practices and so on if the Guidance document matures.

@kcoyle

This comment has been minimized.

Copy link
Contributor Author

@kcoyle kcoyle commented Sep 30, 2019

I'm fine with leaving it in as long as a good explanation is given that informs readers.

@nicholascar

This comment has been minimized.

Copy link
Contributor

@nicholascar nicholascar commented Oct 1, 2019

I'm fine with leaving it in as long as a good explanation is given that informs readers.

Would you like to suggest any wording changes to what's already in the section then?

@kcoyle

This comment has been minimized.

Copy link
Contributor Author

@kcoyle kcoyle commented Oct 1, 2019

I'll let the editors do that.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Oct 2, 2019

@larsgsvensson yes honestly I don't know how to phrase it... The IETF doc is clearly your work, and it belongs to the line of profile work, so it's clearly more than mere related work (as per my earlier comment on the topic). But I don't know if formally it can qualify as output of the W3C group, i.e. as one item on the homepage of the group, on the same level as other deliverables. WG outputs are generally in the W3C domain. And our charter refers the IETF in a cautious way, to say the least (check the two occurrences there).

Maybe I can sum up by saying that I'm keen to present our readers a landscape that is relevant for them, and that I'm also eager to follow a line of least effort in discussions about pure formalities, which make not much difference for readers?

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Nov 12, 2019

There seems to be a consensus to leave as is here - I wont add this to 3PWD - we can vote to close

@kcoyle

This comment has been minimized.

Copy link
Contributor Author

@kcoyle kcoyle commented Nov 12, 2019

Actually, Antoine asks that the IETF document be removed from this section. I agree, but I also think that something about it needs to be added to the motivation section.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Nov 12, 2019

Just to make things clear, I think it should be in this section, but not listed in the same list as the other "pure" WG docs.

@kcoyle

This comment has been minimized.

Copy link
Contributor Author

@kcoyle kcoyle commented Nov 13, 2019

That's fine with me, but I do think it would be a good idea to say a bit more about how it relates to Conneg in the motivation section. Not a lot, but a sentence or two, since the two efforts are mutually motivating.

@nicholascar nicholascar added this to the 4PWD milestone Nov 19, 2019
@nicholascar nicholascar modified the milestones: 4PWD, Conneg 3PWD Nov 27, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.