Documentation


#1

This is a proposed new standard glossary term. See this post for background on this review track. To comment on the term below either click the blue “Reply” button at the bottom or select a passage of text in the term and click the “Quote” pop-up to create a comment about that section only.

Short Definition: Written information that describes a resource to foster discovery, access, and use.

Extended Definition: Written information that describes a resource to foster discovery, access, and use. Minimally, documentation should include basic descriptive information about the resource, such as the title, abstract, authors, date of publication, publisher or distributor, and intellectual property rights associated with the resource. Documentation also should include information about the creation and provenance of the resource, other contributors and sponsors, the quality of the resource, reviews that have been conducted, how the resource has been used, requirements or tools needed to use the resource, and assumptions or constraints for using the resource.

Synonyms: Descriptive Information, Description, Supporting Information

Acronym:

Related Terms: Metadata, Catalog Entry, Research data article, Codebook

Sources:

Term Lead: Bob Downs


#2

Do we need a definition of documentation? I think the definition provided is actually quite a good start, but I am not sure how much it is needed.

Documentation is a very broad sort of term, with many different shades of meaning. Generally it implies a text of some kind which comments on another ‘resource’. The implication is typically that the documentation provides some kind additional context, help, etc. in relation to the resource in question. I would add that a big part of understanding this definition hinges on what we mean by a ‘resource’. We cannot do much with this definition without first understand what is, and is not, a ‘resource’

Also, can documentation do more than foster discovery, access, and use? Are there other functions associated with documentation? If so, we should mention these. Does anything containing instructions and/or explanations count as documentation? The intuitive answer is, of course, no. But we must beware that our definitions are sufficiently free of ambiguity, often at the risk of being pedantic at times.

I think lots of things can fall under the definition of documentation as it is described here, and many of them are probably not what we mean by documentation in the RDM context.


#3

Data documentation is the descriptive record of the context and substance of the data in a specific research endeavour. The objective of documentation is to facilitate the use of data within research and its reuse by others. Within research, documentation serves as an official record of who does what with the data, why, when, where, and how. This includes the administrative information supporting the research as well as the detailed description of the elements in the data. The goal of well-written data documentation is to describe the data so that it is independently understandable. This OAIS principle stipulates that digital content can be interpreted and understood without requiring the person who originally prepared it to be present to explain it. Documentation of this quality is vital for others to reuse the data.


#4

Thank you Matt and Chuck for your comments. “Documentation” is a term that is commonly heard in the context of research data management which is a good reason for defining the term. What is, “a well documented dataset,” for example? The proposed definition is closer to administrative metadata than to the broader definition suggested by Chuck which includes both the administrative metadata, the “deep” metadata, and any other information needed for the data to be independently understandable and re-usable. I will recommend this broader definition for IRiDiuM. On that basis, anyone like to suggest a short definition? Here’s a start, perhaps:
Short definition: The administrative metadata, deep metadata, and all other information needed for the data to be independently understandable without recourse to the data originator(s).


#5

I can see ‘administrative metadata’ being confused with ‘administrative data’. Perhaps definitions can clearly differentiate.


#6

This topic was automatically closed after 0 minutes. New replies are no longer allowed.


#7

#8

This topic was automatically closed after 0 minutes. New replies are no longer allowed.


#9

#10