Antoine,
>
> > On 6/8/15 12:49 PM, Antoine Isaac wrote:
> >> R-208: "A place for human-readable documentation for properties"
> >> http://lelystad.informatik.uni-mannheim.de/rdf-validation/?q=node/415
> >>
> >> The label is not very precise. We suggest "documentation of property
> >> usage from the perspective of the application profile."
> >>
> >> The scope could be broader, not only properties, but classes and maybe
> >> other elements, including constraints and axiom. But presently we can't
> >> really identify all these elements so we can't really name this broader
> >> scope. So we just suggest to postpone this.
> >
> >
> > How about just making this about having human-readable documentation of
> all aspects of the AP? The way that I was thinking about this is quite simply that
> the AP language would have properties for documentation throughout -- like
> rdfs:comment but specifically something that you know describes the aspect of
> the AP at that point - property, class, graph, validation, whatever. We want to
> have a specific way to include comments that are intended to be shown to
> programmer-users of the AP.
> >
>
>
> Yes, we're on the same line. The problem Hugo and I was basically a naming
> one. We felt "all aspects of the AP" was raising to many questions in the eye of
> a new reader, so we kept our suggestion conservative. It also allowed to easily
> mention 'usage' in the title.
>
>
>
> >
> > There's also perhaps another form of documentation that we might want, and
> that is metadata creator documentation -- the documentation that would be
> included in input forms, for example. "This field takes a date in the form YYYY-
> MM-DD."
> >
> > I don't know if these are two different kinds of comments, or if they can be
> satisfied with a single property.
> >
>
>
> They're probably satisfied with a single property. If we keep 'usage' in the
> requirement. This includes input forms, I think.
> I mean, if a property has a constraint that says that its value comply with the
> ISO standard for dates, then I expect that a "documentation for property usage"
> should be like the one you've written.
>
>
> Lars wrote:
> > Does that mean that the label should be "documentation of property usage
> from the perspective of the application profile"
> >or "A place for human-readable documentation of property usage from the
> perspective of the application profile"? I'd prefer the latter...
> >
>
>
> Fair enough, we had forgotten the 'human-readable' and it's certainly worth to
> keep it in!
> I don't like 'a place' though (and it makes the title longer, which will be an issue
> if we extend it as discussed above).
>
>
> So in conclusion I'd now suggest
> "human-readable documentation of property usage from the perspective of the
> application profile."
> or if we want to broaden the scope right now
> "human-readable documentation of usage of all elements from the perspective
> of the application profile."
I'd go for the broader one: "human-readable documentation of usage of all elements from the perspective of the application profile."
Best,
Lars
|