Primer 0.1

[EricReese15]

Fully updated primer based on user and Helpdesk feedback

closes #1239, closes #614

[jpmckinney]

We need to decide what (if anything) to retain from these pages (if retained, need to add to Guidance):

• https://standard.open-contracting.org/1.1/en/getting_started/building_blocks/
  • This is covered in the reference section (schema/reference) and some is covered on primer/how, though maybe some examples could be retained.
• https://standard.open-contracting.org/1.1/en/getting_started/releases_and_records/
  • This is largely covered by primer/releases_and_records, though maybe some examples could be retained. I think "easy releases" and other pages from Change history and System Architectures #997 might cover the rest, but I'm not sure. The animation, I think, is not easily understandable outside helpdesk analysts who are familiar with the "block" visualization.

@yolile What do you think?

I'm not sure if/where to re-integrate the OCDS example:

```{jsoninclude} ../examples/contract.json
:jsonpointer: /releases
:expand: releases, tender, awards, contracts, period, value, items, tag, parties, documents
```

[jpmckinney]

Preview should be available here if build succeeds: https://standard.open-contracting.org/staging/primer_0.1/en/primer/

[yolile]

For https://standard.open-contracting.org/1.1/en/getting_started/building_blocks/:

• We can move https://standard.open-contracting.org/1.1/en/getting_started/building_blocks/#codelists worked example to the map section, where the other worked examples are
• https://standard.open-contracting.org/1.1/en/getting_started/building_blocks/#extensions This is already covered by the specific Extensions page
• https://standard.open-contracting.org/1.1/en/getting_started/building_blocks/#building-blocks-fields could be preserved in https://standard.open-contracting.org/staging/primer_0.1/en/primer/how/#how-does-the-ocds-work after "When mapping your data to the OCDS our sing OCDS data, you will encounter a number of common data fields and structures, which are described by the schema.. " section

For https://standard.open-contracting.org/1.1/en/getting_started/releases_and_records/:

• We have a complete video with examples now, so I'm ok with removing the animation.
• https://standard.open-contracting.org/staging/primer_0.1/en/primer/releases_and_records/ doesn't mention packages and their metadata at all is that on purpose?
• I think that the releases and records examples that are part of https://standard.open-contracting.org/1.1/en/getting_started/releases_and_records/ are useful and not covered anywhere else, so we might want to keep them

[jpmckinney]

Thanks! I’ll move those to new pages. Can you review the rest of the PR in the meantime?

[yolile]

Can you review the ready of the PR in the meantime?

Sure, I will!

[jpmckinney]

For https://standard.open-contracting.org/1.1/en/getting_started/building_blocks/:

• We can move https://standard.open-contracting.org/1.1/en/getting_started/building_blocks/#codelists worked example to the map section, where the other worked examples are

I don't think this example does much more than the example in https://www.open-contracting.org/resources/ocds-1-1-codelist-mapping-template-guidance/, which is what we want people to use for mapping codelists. What do you think?

• https://standard.open-contracting.org/1.1/en/getting_started/building_blocks/#building-blocks-fields could be preserved in https://standard.open-contracting.org/staging/primer_0.1/en/primer/how/#how-does-the-ocds-work after "When mapping your data to the OCDS our sing OCDS data, you will encounter a number of common data fields and structures, which are described by the schema.. " section

When preparing the Primer, Eric and I were not sure that the metaphor of "building blocks" was actually very helpful.

• We might not preserve common definitions for items, etc., because extending them can have unintended consequences Guidance around extending subschema (building blocks) #606, in which case we will not have "building blocks" in the same way.
• It's not clear that it is especially relevant for an implementer to learn that some objects follow the same schema in different parts of the data. It seems okay to learn this in the schema reference.
• I created Eliminate language of "building blocks" #1347 about changing the terminology.

So, I'm okay with not having this section. What do you think?

I'll create an issue to add example data to the schema reference, since that is the main benefit of this section. #1348

For https://standard.open-contracting.org/1.1/en/getting_started/releases_and_records/:

• https://standard.open-contracting.org/staging/primer_0.1/en/primer/releases_and_records/ doesn't mention packages and their metadata at all is that on purpose?

The old page says very little about packages (only mentioning the uri metadata). Since packages are going to become optional #1084, it is not important to mention them in the Primer.

• I think that the releases and records examples that are part of https://standard.open-contracting.org/1.1/en/getting_started/releases_and_records/ are useful and not covered anywhere else, so we might want to keep them

Do you mean the two Example and Hint boxes? Isn't the Example covered by: https://standard.open-contracting.org/1.1/en/guidance/build/change_history/

For the Hint, it is a useful demonstration of the value of compiled releases. However, we know that publishers are unlikely to correctly implement the merging behavior (it's quite easy to have bugs), and we know that very few publishers offer compiled releases anyway (unless they do "easy releases"). So, I think we've accepted that the registry is the way for users to access compiled releases.

[yolile]

I don't think this example does much more than the example in https://www.open-contracting.org/resources/ocds-1-1-codelist-mapping-template-guidance/, which is what we want people to use for mapping codelists. What do you think?

True, I found this mapping a local codelist worked example outline, which means that at some point we thought that it would be useful to have that worked example, I guess. (see also the worked examples spreadseet)

It's not clear that it is especially relevant for an implementer to learn that some objects follow the same schema in different parts of the data. It seems okay to learn this in the schema reference.

Yes, actually, I think that it is more relevant for them to learn about that while developing an extension, for example, which is something more advance and requires understanding/looking at the schema reference, so I'm ok with not having this section too. (fun fact: I've never managed to found a correct/nice/perfect translation for this in Spanish, so I'm happy in that sense too)

Since packages are going to become optional #1084, it is not important to mention them in the Primer.

That is what I thought, all good then.

Do you mean the two Example and Hint boxes? Isn't the Example covered by: https://standard.open-contracting.org/1.1/en/guidance/build/change_history/

It is partially covered, the https://standard.open-contracting.org/1.1/en/getting_started/releases_and_records/#repeating-previous-information section is not covered and I think that it contains useful guidance about minimal updates (recently one data user referenced this section of the documentation, so at least it is useful for some people)
And for compile releases and easy releases, maybe we can add a reference to the easy releases guidance in https://standard.open-contracting.org/1.1/en/guidance/build/change_history/?

[jpmckinney]

Agreed on a call to:

• Update the codelist mapping template guidance with a better example, rather than have guidance in both the template's guidance and in the docs. Tracked in CRM-7491
• Create an issue to re-introduce a worked example for minimal updates and change history Example: Minimal updates in change history #1364

And in this PR, to:

• Link to easy_releases from change_history, for guidance on setting the release id 2d0b9c6