Closed baskaufs closed 8 years ago
I would like to see this be a "Best Practice." That said, I am not sure what is the difference between "Motivation" and "Rationale."
I agree that it should be at least a best practice. Another way to focus the content might be to just recommend a "Justification" and say what kinds of things should be in there.
On Sat, Apr 16, 2016 at 1:40 PM, Bob Morris notifications@github.com wrote:
I would like to see this be a "Best Practice." That said, I am not sure what is the difference between "Motivation" and "Rationale."
— You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub https://github.com/tdwg/vocab/issues/31#issuecomment-210853204
I've looked at several W3C and IETF documents and none of the ones that I looked at had anything more specific than an introduction section. All of the introduction sections basically said "what the thing was" and "what the purpose was for the thing". Perhaps we could simply specify that documents should have an introduction that succinctly states the subject and purpose of the document. I think that "purpose" could encompass "justification", "motivation", and "rationale" as much as the authors though was necessary. For examples from three organizations, see https://www.w3.org/TR/sparql11-query/ http://dublincore.org/documents/dc-rdf/ https://tools.ietf.org/html/rfc3986
On the 2016-05-04 call there was a consensus that a single introductory section, non-proscriptive, should define the purpose of the standard.
Edited section 3.2.3.3 to clarify this.
The previous draft documentation spec specified that a standard should include information on "Motivation" and "Rationale". There also seems to be a practice of including "Audience". Does the new documentation need to require or suggest that these sections be present, or can we just leave this up to the authors? See section 3.2.3.3 of the documentation spec