Change order of codelists in Reference

[JachymHercher]

When going through OCDS, I often go directly to one of the codelists in https://standard.open-contracting.org/latest/en/schema/codelists/, but then I am unsure whether it is open or closed, so I scroll up or down to find which section it is in. This seems a bit clumsy.

1. Wouldn't it be better if each codelist has an [open] or [closed] attribute below/after it's title?
2. If we added such an attribute, we could also remove the open / closed subsections. I'm not sure how useful they are (do people want to read about "all closed codelists" in one go? Seareching for codelists probably happens via ctrl-f.) and we could then have the same sorting across the whole page (see below).
3. I'm not sure how the codelists are sorted. Doesn't seem to be alphabetical, by importance, nor chronological? I would go by importance/chronology.

(This issue is about ordering codelists as whole, #1198 is about ordering codes within codelists.)

[jpmckinney]

To avoid merge conflicts, and since the reference section for 1.1 is frozen, I've moved this to 1.2.

In #1075 I suggest one page per codelist, because some codelists are extremely long (like currency).

In that case, we will definitely need a way to indicate open/closed in an easily recognizable way.

To make it easier to find a known codelist, we can sort the codelists alphabetically in the navigation.

On the landing page for all the codelists (e.g. /schema/codelists/), we can instead logically group and order the links to the individual codelist pages (e.g. a Status section with Tender status, Award status, Contract status, Milestone status, in that order). This grouping would be easier for people who are discovering or learning about the standard.

[duncandewhurst]

@jpmckinney your suggestions sound good to me. I think that @odscjen or I can progress with this issue as follows:

1. Move codelists to individual pages
2. Add a badge below each codelist page title to indicate whether the codelist is open or closed. The badges can link to the sections of the codelist landing page that explain open and closed codelists.
3. Order the codelist pages alphabetically in the navigation
4. Propose a grouping and ordering for the links from the codelist landing page to the individual codelist pages

Are you happy for one of us to do that?

[jpmckinney]

Yes, but please check all open PRs to review whether any touch the same pages. If there are any, you can report your findings here and we can decide how to proceed.

[duncandewhurst]

The only PR that touches codelists.md is #1660. It makes one non-whitespace change.

However, links to codelist documentation will need to be updated, e.g. ../../schema/codelists.md#party-scale will change to ../../schema/codelists/party_scale. I think that will cause conflicts with the following changes:

#1660:

• https://github.com/open-contracting/standard/pull/1660/files#diff-0a32de0359d87c42644de479f85c247d27d5f0dbb0959f162fb4b8b9389b1bb6L14
• https://github.com/open-contracting/standard/pull/1660/files#diff-0a32de0359d87c42644de479f85c247d27d5f0dbb0959f162fb4b8b9389b1bb6L46

#1680:

• https://github.com/open-contracting/standard/pull/1680/files#diff-ad7a21639d13433e0d0f06126a4ce0f979ab8e86ed7f6a28a439df33458419c9L27
• https://github.com/open-contracting/standard/pull/1680/files#diff-af676d9a2255c8a21a90169ef19b49248b12212bb6e4663a92102f2bde4c7114L34
• https://github.com/open-contracting/standard/pull/1680/files#diff-0a32de0359d87c42644de479f85c247d27d5f0dbb0959f162fb4b8b9389b1bb6L13
• https://github.com/open-contracting/standard/pull/1680/files#diff-0a32de0359d87c42644de479f85c247d27d5f0dbb0959f162fb4b8b9389b1bb6L14
• https://github.com/open-contracting/standard/pull/1680/files#diff-0a32de0359d87c42644de479f85c247d27d5f0dbb0959f162fb4b8b9389b1bb6L26
• https://github.com/open-contracting/standard/pull/1680/files#diff-0a32de0359d87c42644de479f85c247d27d5f0dbb0959f162fb4b8b9389b1bb6L46
• https://github.com/open-contracting/standard/pull/1680/files#diff-0a32de0359d87c42644de479f85c247d27d5f0dbb0959f162fb4b8b9389b1bb6L46
• https://github.com/open-contracting/standard/pull/1680/files#diff-0a32de0359d87c42644de479f85c247d27d5f0dbb0959f162fb4b8b9389b1bb6L46

Shall we prepare the PR without updating links and leave it as a draft until at least #1680 is merged?

[jpmckinney]

You can start on the PR, without updating links :)

[odscjen]

Initial suggestion for logical grouping of the codelists:

Release level

releaseTag
linkRelationType
relatedProcess
initiationType - deprecated

Organization

organizationRole
partyScale

Tender stage

method
procurementCategory
extendedProcurementCategory
awardCriteria
submissionMethod - deprecated

Status

tenderFinalStatus
awardFinalStatus
contractFinalStatus
milestoneStatus
tenderStatus - deprecated
awardStatus - deprecated
contractStatus - deprecated

Scheme

classificationScheme
organizationIdentifierScheme
relatedProcessScheme

Types

documentType
mediaType
milestoneType

ISO codes

country
currency
language

The groupings are not all semantically the same but I was trying to think about this as a user and what would make sense if I was trying to understand how the codelists fit into the standard. So a few comments on my rationale for the above:

• unless there's a clear chronological order (e.g. statuses) I've just ordered within the grouping alphabetically and then put deprecated lists at the bottom of the group
• I've tried to order the groups by importance or chronology based on when a user would come across them, this is very much imperfect due to some occurring at multiple stages.
• I've put the codes that are only used in a Tender field together as if I was looking for 'method' there's a good chance I'd also be looking for 'procurementCategory' etc.
• I've put 'organizationIdentifierScheme' with the other schemes rather than the other parties codelists as the other 2 refer to the organization itself, where the scheme codelist is not.
• By grouping the 3 ISO codes it emphasises that OCDS makes use of external standards were appropriate, and all 3 can be used in multiple places and stages in a release. I considered adding 'mediaType' as it's also an external list (and changing the group name to External codes) but decided it was better with the other release level lists
• I did consider trying to group them all by stage or subschema, but too many codelists are used in subschema that appear in multiple stages and at different levels, e.g. 'language' is used in Document which appears in tender, Award, Contract and Milestone, and it's also used in language at the release level.
• I'm not particularly happy with the 'Release' group but they do all appear outside of the contracting and planning process stages so they all have that in common

@jpmckinney @duncandewhurst any thoughts?

[duncandewhurst]

Thanks, Jen! The reuse of codelists in different places certainly makes it tricky. We could consider repeating some codelists, if you think that would enable a more useful grouping.

I like your proposal, but I think the deprecated codelists can go under their own heading and I don't like the 'types' group because milestoneType doesn't really have anything in common with the other two codelists.

I've suggested some changes below, although I still don't love the 'Classifications' group. To reduce the number of groups, we could consider moving the release level codelists under the 'procedure and object of procurement' heading.

Release level

• releaseTag
• linkRelationType Moved to external codelists because I think it's expected to be used fairly infrequently
• relatedProcess
• relatedProcessScheme

Organization

• organizationRole
• organizationIdentifierScheme
• partyScale

Tender stage Procedure and object of procurement

• method
• procurementCategory
• extendedProcurementCategory
• awardCriteria
• milestoneType

Status

• tenderFinalStatus
• awardFinalStatus
• contractFinalStatus
• milestoneStatus

Classification

• classificationScheme
• documentType
• organizationIdentifierScheme Moved to organization as it's only used in that context
• relatedProcessScheme Moved to release level to sit alongside relatedProcess

Types

• documentType Moved to classifications as it's a classification of document types
• mediaType Moved to external codelists
• milestoneType Moved to procedure and object of procurement because milestones describe key events in contracting/planning processes, or related to delivery.

ISO codes External codelists

• country
• currency
• language
• linkRelationType
• mediaType

Deprecated codelists

• initiationType
• submissionMethod
• tenderStatus
• awardStatus
• contractStatus

[jpmckinney]

• I prefer leaving the deprecated codelists at the ends of their respective sections. Imagine we already had this content structure – it would be strange to move things around after a deprecation.
• Although Procedure or object of procurement is more correct, OCDS users are more familiar with Tender, and it is the name of the subschema in which these codelists are used, so let's call it simply "Tender"
• Create a section "Related process" for the two related process codelists.
• Simply use an "Uncategorized" section for leftovers.

For deprecated codelists, we can add a "deprecated" badge: https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html

For external codelists, we can maybe name their source

So:

Uncategorized

• releaseTag
• classificationScheme
• documentType
• milestoneType
• initiationType (deprecated)

Status

• tenderFinalStatus
• awardFinalStatus
• contractFinalStatus
• milestoneStatus
• tenderStatus (deprecated)
• awardStatus (deprecated)
• contractStatus (deprecated)

Organization

• organizationRole
• organizationIdentifierScheme
• partyScale

Tender

• method
• procurementCategory
• extendedProcurementCategory
• awardCriteria
• submissionMethod (deprecated)

Related process

• relatedProcess
• relatedProcessScheme

External

• country (ISO 3166-1 alpha-2)
• currency (ISO 4217)
• language (ISO 639-1)
• linkRelationType (IANA Link Relations)
• mediaType (IANA Media Types)

[duncandewhurst]

Looks good to me!