search

tdwg / vocab

Vocabulary Maintenance Specification Task Group + SDS + VMS
11 stars 6 forks source link

Specification of Introduction, Motivation, and Rationale sections #31

Closed baskaufs closed 8 years ago

baskaufs commented 8 years ago

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

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

tucotuco commented 8 years ago

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

baskaufs commented 8 years ago

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

tucotuco commented 8 years ago

On the 2016-05-04 call there was a consensus that a single introductory section, non-proscriptive, should define the purpose of the standard.

baskaufs commented 8 years ago

Edited section 3.2.3.3 to clarify this.