>>> 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."
>


OK, let's try it!

Antoine