Specifications should be found in the same location

[brianterry-ama]

Description

Currently, the specifications for dataset documents and product definitions are located in separate files within the repository:

• Dataset Document Specification: Found in SPECIFICATION.md.
• Product Definition Specification: Found in SPECIFICATION-odc-product.md.

Having these specifications in different locations can cause confusion and make it harder for new users to find relevant information when defining datasets and products.

Additionally, we should provide better clarity on the odc-type specification. If anyone has additional context or suggestions, please contribute!

Proposal

To improve clarity and accessibility, the dataset document and product definition specifications should be grouped in the same location. Possible solutions include:

1. Placing both specifications within a clearly named directory (e.g., specifications/) to indicate they are related.
2. Ensuring proper cross-referencing between the documents, making it clear where users should look for complete information.

The Documentation Committee will tackle this at one of the office hours and create a brief readme introducing the specifications.

Rationale

• Easier Discovery – Users should not have to search multiple locations for related specifications.
• Consistency – Keeping specifications together ensures they are updated and maintained in sync.
• Better Documentation Flow – A unified location helps in understanding the relationship between dataset documents and product definitions.

References

• SPECIFICATION.md
• SPECIFICATION-odc-product.md
• odc-type specification