Creating Good Documentation
[email protected] 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:[email protected]
Links