Consider re-organizing Reference section

[jpmckinney]

• The Reference section doesn't offer a clear path for users. Its landing page doesn't sign-post to all sub-pages, so some readers might never read, e.g. the Identifiers page.
• Release Reference is very long and will get longer as more fields/objects are added. In a much larger schema like Schema.org, they split each object into its own page, for example: https://schema.org/docs/full.html
• The long tables are useful when you are looking up a term, but otherwise break up the page and make it hard to scan. It might be better to have at most one long table per page, and for that table to be at the end (like on Schema.org).

The documentation of APIs with a lot of methods and/or objects can also serve as inspiration: for example, Google's and GitHub's developer docs.

[jpmckinney]

Looking at the content, we have:

Thematic content

• https://standard.open-contracting.org/latest/en/schema/identifiers/
• https://standard.open-contracting.org/latest/en/schema/reference/#release-handling
• https://standard.open-contracting.org/latest/en/schema/reference/#language
• https://standard.open-contracting.org/latest/en/schema/merging/
• https://standard.open-contracting.org/latest/en/schema/conformance_and_extensions/

Schema/Codelist references

• https://standard.open-contracting.org/latest/en/schema/reference/#release-structure
• https://standard.open-contracting.org/latest/en/schema/reference/#building-block-reference
• https://standard.open-contracting.org/latest/en/schema/codelists/

Package-related content

• https://standard.open-contracting.org/latest/en/schema/records_reference/ (records can be seen as a way of packaging individual releases, compiled releases and versioned releases – they don't add new data)
• https://standard.open-contracting.org/latest/en/schema/release_package/
• https://standard.open-contracting.org/latest/en/schema/record_package/

JSON Schema browsers

• https://standard.open-contracting.org/latest/en/schema/release/
• https://standard.open-contracting.org/latest/en/schema/release_package/
• https://standard.open-contracting.org/latest/en/schema/record_package/

[jpmckinney]

In terms of re-architecture, we might consider:

• Lead with the thematic content, starting with one page per theme
• Provide the Schema/Codelist references, with one page per object/codelist, so that there is only one big table per page. Presently, I believe a lot of users haven't read the explanatory content above each table, because it's very easy to miss.
• Provide the schema browsers in one section, with three sub-pages.
• Provide the package-related content in one section, with sub-pages as needed.

[jpmckinney]

On each sub-schema page, we can implement a new directive to list where that sub-schema is referenced from (with a link to the relevant page), e.g. the Document sub-schema page would like to the Tender, Award and Contract pages.

[duncandewhurst]

Presently, I believe a lot of users haven't read the explanatory content above each table, because it's very easy to miss.

Strongly agree!

[stevieflow]

Hi @jpmckinney @duncandewhurst

Just wanted to offer in this mix the example of the IATI docs, whereby there's a specific / persistent URL for each and every "data field" of the standard - eg

https://iatistandard.org/en/iati-standard/203/activity-standard/iati-activities/iati-activity/transaction/sector/

This then included left-hand-side navigation that places you in situ / context

I have always found this very useful, both in terms of specificity and navigability, of the schema/standard

Thanks

[jpmckinney]

Thank you for sharing!

I can see the utility given that XML elements have attributes that require documentation.

Since OCDS is JSON, there is not much more to add beyond the field title, type and description, so pages for each field would be very short. I think there's more utility to seeing all an object's fields on one page.