Creating Good Documentation

Ted.Habermann@noaa.govNOAA National Geophysical Data Center

https://www.nosc.noaa.gov/dmc/swg/wiki

Designated Communities - Users

Data preservation is communicating with the future

“Create a time capsule with your class to remember the year. Often we forget about our experiences unless they are recorded. It will be interesting to have documentation of the past.”

The Community Understanding Foundation

A Security exception is required to view this page because we have a self-signed certificate.

It is safe!

Use Cases and Spirals

Spiral 1:Initial ContentSpiral 1:Initial Content

Metadata ContentIndependent of standardMetadata ContentIndependent of standard

StandardGuidance /

Implementation

StandardGuidance /

Implementation

Check BackWith UsersCheck BackWith Users

Spiral 2-N: Scientific QuestionsNew RequirementsNew Use Cases

Check BackWith Data Collectors/

Providers

Check BackWith Data Collectors/

Providers

Data Providers / Scientists Standards ExpertsData Stewards

IdentificationIdTitleAbstractResource DateTopic CategoryTheme KeywordMetadata ContactScience Contact

IdentificationIdTitleAbstractResource DateTopic CategoryTheme KeywordMetadata ContactScience Contact

ExtentGeospatial Bounding BoxTemporal Start/EndVertical Min/MaxPlace Keywords

ExtentGeospatial Bounding BoxTemporal Start/EndVertical Min/MaxPlace Keywords

DistributionDistributor ContactOnline ResourceDistribution FormatData Center KeywordsBrowse Graphic

DistributionDistributor ContactOnline ResourceDistribution FormatData Center KeywordsBrowse Graphic

Text SearchesPurposeExtent DescriptionLineage StatementProject Keywords

Text SearchesPurposeExtent DescriptionLineage StatementProject Keywords

Quality/LineageSourcesProcess StepsQuality Reports / Coverages

Quality/LineageSourcesProcess StepsQuality Reports / Coverages

Acquisition InformationInstrumentPlatformInstrument KeywordsPlatform Keywords

Acquisition InformationInstrumentPlatformInstrument KeywordsPlatform Keywords

Potential Spirals

Content InformationAttribute TypeAttribute NamesAttribute DefinitionsAttribute Units

Content InformationAttribute TypeAttribute NamesAttribute DefinitionsAttribute Units

Documenting Spirals

Web Accessible Folders

MetadataRepositoryISO 19115,

19115-2, 19119 and extensions

MetadataRepositoryISO 19115,

19115-2, 19119 and extensions

THREDDSTHREDDS

netCDFnetCDF

DIF, FGDCDIF, FGDC

SensorMLSensorML

WCS, WMS, WFS, SOS

WCS, WMS, WFS, SOS

ISOISO

KMLKML

Documentation Without Borders

DS_Aggregates: Directory Structures

MI_Metadata(from Metadata entity set information)

<<Abstract>>DS_Aggregate DS_DataSet

DS_SeriesDS_OtherAggregate DS_Initiative

DS_StereoMate DS_Platform DS_ProductionServiceDS_Sensor

+ describes 0..*

+has1..*+ seriesMetadata

1..*

+ part of 0..*

+ composedOf1..*

MultipleAggregation

+ superset 0..*

+ subset 0..*

+ series0..*

There are many kinds of DS_AggregatesA DS_Aggregate has one or more seriesMetadataA DS_Aggregate is composed of one or more DS_Datasets

Platform DocumentationDS_PlatformseriesMetadata MI – Platformsubset DS_Sensor DS_DataSet MI – Deployment 1 MI – Deployment 2 MI – Deployment 3 seriesMetadata MI - Sensor

Platform DocumentationDS_PlatformseriesMetadata MI – Platformsubset DS_Sensor DS_DataSet MI – Deployment 1 MI – Deployment 2 MI – Deployment 3 seriesMetadata MI - Sensor

Project DocumentationProject Documentation

Program DocumentationOffice of Climate Observations

Program DocumentationOffice of Climate Observations

THREDDS Data ServernetCDF filesOther formats

THREDDS Data ServernetCDF filesOther formats NcML XSLTXSLT

ISO

Network DocumentationMI – Network Extent Distribution

Network DocumentationMI – Network Extent Distribution

Deployment DocumentationMI – DeploymentDeployment DocumentationMI – Deployment

AggInfoLWCit

Other PlatformsOther Platforms

Other DeploymentsOther Deployments

AggInfoCRef

AggInfo CRef

AggInfoLWCit

AggInfoLWCit

Other NetworksOther Networks

AggInfo CRef

Other ProjectsOther Projects

AggInfo CRef

<<CodeList>>MX_ScopeCode

+ attribute + feature + attributeType + featureType+ collectionHardware + propertyType+ collectionSession + fieldSession+ dataset + software+ series + service+ nonGeographicDataset + model+ dimensionGroup + tile+ productionSeries + initiative+ sensorSeries + sensor+ platformSeries + otherAggregate+ transferAggregate + stereoMate

Documentation Architecture

Documentation ArchitectureOceanSites is a complex collection of information at many levels. The documentation architecture provides an overview of those levels and the relationships between them. One model includes five levels:

PlatformPlatformProjectProjectProgramProgram NetworkNetwork DeploymentDeployment

file.ncfile.ncfile.ncfile.nc file.ncfile.nc file.ncfile.nc

THREDDS Catalogs

THREDDS Catalogs

Current granule documentation feeds into this system to create discovery metadata that can feed existing portals

Principle:Scientists do science and write scientific dataDocumentation experts write documentation

Documentation Extraction

file.ncfile.ncfile.ncfile.nc file.ncfile.nc file.ncfile.nc

THREDDS Catalogs

THREDDS Catalogs

DocumentationRepository

DocumentationRepositoryISO XML

Spiral TrackerSpiral TrackerHTML

NcMLNcML

Documentation in Three Dialects

DocumentationRepository

DocumentationRepositorySpiral TrackerSpiral TrackerNcMLNcML

Documentation Repository / Portal

Other ISO 19115 Information:https://www.nosc.noaa.gov/dmc/swg/wiki/index.php?title=Category:ISO_19115

Creating Good Documentation:https://www.nosc.noaa.gov/dmc/swg/wiki/index.php?title=Creating_Good_Documentation

Web Accessible Folder:http://www.ngdc.noaa.gov/metadata/published/19115/isoMetadataHome.html

Questions:ted.habermann@noaa.gov

Links