Explaining the documentation structure

[JachymHercher]

As a reader of the OCDS documentation, it is not clear to me what is the relationship between / what to expect of "Getting Started", "Guidance" and certain parts of "Reference" (esp. "Merging", "Identifiers" and "Conformance and extensions").

My best guess is:

• "Getting Started" is something like "understanding what OCDS is" / "very basic info"
• "Guidance" is something like "step by step guidance when you are implementing" / "more advanced info"
• "Reference" is normative, while the above-mentioned are not normative.

I would suggest the following changes:

• Explaining the difference between the three sections in https://standard.open-contracting.org/latest/en/getting_started/. (This issue might be resolved by the ongoing review of the "Getting Started" section.)
• Emphasize that everything in "Reference" is normative in https://standard.open-contracting.org/latest/en/schema/. (Currently, it is only mentioned in Normative and non-normative content).
• Review the three sections "from top to bottom". In particular, "mapping the hard cases" seems to contain a lot of important content that should be somewhere else more prominently, possibly even in the normative "Reference" section.

[jpmckinney]

Thanks, @JachymHercher. @EricReese15's work on the Primer (and home page) can address the first two bullets. For the last bullet, we'll have to do this iteratively. The new theme that @choldgraf is working on will help with the navigational issues.

[jpmckinney]

For the third bullet, could you give some examples? Once that's clearer, we can start to list which content ought to move.

[JachymHercher]

Point 1 and 2 are indeed covered by the new primer, specifically:

Guidance: Step-by-step instructions on how to design and implement an OCDS publication, including practical examples
Reference: The OCDS data model (schemas, codelists and validation rules) as well as specific rules that need to be followed to publish OCDS data

It doesn't explicitly use the word "normative", but that makes sense, as it's jargon.

---

Concerning point 3, my assumption is that everything we want people to do according to the Guidance (esp. hard cases) must be based on some text (typically a description of a field or code) in Reference. The purpose of Guidance is just to draw together the "rules" from Reference and give them to the users in an easy-to-understand way. If this assumption correct, then I'm unsure whether the following instructions in Guidance have a corresponding basis in Reference:

1. Do we set somewhere in Reference that for multistage processes you need multiple ocids? It's not in https://standard.open-contracting.org/latest/en/schema/identifiers/#contracting-process-identifier-ocid, just in https://standard.open-contracting.org/latest/en/guidance/map/related_processes/.

2. Do we set somewhere in Reference when to put information only in awards, when only in contracts and when in both? Along the lines of https://standard.open-contracting.org/latest/en/guidance/map/awards_contracts/#id1, cf. Guidance on awards and contracts: when to fill in one and/or the other #1400.

3. According to https://standard.open-contracting.org/latest/en/guidance/map/organizational_units/, additionalIdentifiers can be used to provide unit identifiers, but this is not reflected in the field's description.

4. According to guidance/map/contracting_planning_processes.md (pull 1216, merged into OCDS 1.2)

   A planning process ought to have its releaseTag set to 'planning' (or 'planningUpdate'). A contracting process can have releaseTag set to any other value from the codelist. A planning process should not contain the releaseTag 'tender' even if it contains a tender object. The two processes ought to be linked together using the relatedProcesses array in the releases for the contracting process, with the 'planning' code in the related process' relationship array.

   Shouldn't the sentence "A planning process should not contain the releaseTag 'tender' even if it contains a tender object." also be somewhere in Reference?

[jpmckinney]

Yes, that is the purpose of the Guidance section.

1. We haven't yet, because our guidance for related processes is basically a "hotfix" to OCDS 1.x, and was only recently completed in full. That said, now that we've done it, we can add some normative content to the identifiers page.
2. "Overfill" is a common problem in standard implementations. The normative statement that is intended to prevent it is "Its usage of this specification's terms must be consistent with the semantics of those terms." (ref) That statement means that you shouldn't put an award value as the contract value when there is no contract yet, for example. We can perhaps expand the point into a longer section about avoiding overfill – but then that's what the Guidance is doing.
3. Good catch. We should update the field description.
4. I think this is the work of Update all stage object descriptions and release tags #1385

[JachymHercher]

1. & 3. - ok.
2. I'm not 100% sure I get this, maybe lets come back to it after Guidance on awards and contracts: when to fill in one and/or the other #1400.

'

4. Ok, done in ed37c4e.

[JachymHercher]

1. Do we set somewhere in Reference that for multistage processes you need multiple ocids? It's not in https://standard.open-contracting.org/latest/en/schema/identifiers/#contracting-process-identifier-ocid, just in https://standard.open-contracting.org/latest/en/guidance/map/related_processes/.

On second thought, I don't think we need to. The desecription of the schema contains "In multiple stage procedures (e.g. framework agreements with reopening of competition), each round of competition is treated as a separate contracting process." and the description of an ocid includes "Alternatively, this identifier can refer to a planning process or a single stage of a multiple stage procedure." The rules on publication conformance (esp. 2) then seem sufficient to create the obligation that multiple-stage procedures have multiple ocids.

2. Same as above, we don't need more.

3. Created the PR (main change + a few details since I was changing it already):
   i) Main change: "This can be used to provide an internally used identifier for this organization in addition to the primary legal entity identifier." to "This field can also be used to provide an identifier for an organizational unit (for example, an agency branch or a division)." (I hope "internally used identifier" doesn't mean something else, but I'm assuming not and the expression does not appear in https://standard.open-contracting.org/latest/en/guidance/map/organization_identifiers/ nor https://standard.open-contracting.org/latest/en/guidance/map/organizational_units/.)
   ii) "additional / supplemental identifiers" --> "additional identifiers" (unnecessary synonyms)
   iii) "for the organization or participant" --> "for the organization" (everything is an organization by now)

[jpmckinney]

I hope "internally used identifier" doesn't mean something else

The idea was that a publisher might have some way to identify the organization that is not otherwise published elsewhere. For example, the e-GP system might assign database IDs to suppliers, and these IDs don't reconcile with any other system.

That said, we never suggest that these fields are only for reconcilable IDs, so the sentence is unnecessary.