Change Discovery seeAlso documentation does not match Prezi3 seeAlso documentation
mixterj opened this issue · 5 comments
In reviewing the Change Discovery seeAlso documentation I noticed that it does not match the seeAlso documentation for Prezi3.
Specifically the Change Discovery documentation does not reference the use of profile at all. It seems like it would be important to mention this to help with data processing - otherwise the crawler would have to guess the profile or go off to the manifest to get that information, which defeats the purpose of caching this data in the Change Discovery stream.
Another minor issue is the verbiage we use to describe the seeAlso attributes. Prezi3 uses SHOULD for none essential attributes while Change Discovery uses MAY.
Since this part of the spec is really just caching data from the Manifest (which follows Prezi3), I suggest we just copy the documentation from Prezi3 into Change Discovery, with minor changes to put it into the proper Change Discovery API context.
Discussion on 2020-11-11: Agree, should have profile and label described in appropriate sections, mirroring Prezi 3.0.
Looking at the changes refered above, I realize that in the context of the section on ordered collections, one could understand that the motivation for the use of the Dataset type is to indicate that the resource is a dataset (in the sense of data about a set of resources).
So the new text on seeAlso could include an extra clarification about this type, maybe in the line of the explanation given for the type in the activity object's seeAlso ("meaning that it is data rather than a human-readable document.").
After the dataset example, we could add the sentence "Note that alone, the Dataset value for the type property indicates that the resource is data rather than a human-readable document, not that this resource is data about a set of resources."
Would this be ok?
Call 25-11-2020: can be closed when the PR is merged
I am actually not sure anymore whether my comment above is right, in the course of the call we re-questioned some issue: https://docs.google.com/document/d/1TXYze4R4Hi8Qi9ho9e2dYUgm3bPVkSAzBCrFGgFKyJQ/
Sadly I am not sure whether I've marked this comment on the right issue. It might have been for #74 (which we agreed could be closed). I had dozens of tabs open :-/
Call 20-01-2021: the issue can be closed with the current PR is merged. A new (editorial) issue - #85 - has been created to capture the problem that alignment with Prezi3 now creates some ambiguity on the use of the word 'dataset' in different places with different meanings (i.e. in the type element, it is used just to refer to a bunch of data, not exactly the kind of datasets that the Activity Streams are about)