OCDS 1.2: Key changes to socialize

[duncandewhurst]

Let's use this issue to log key changes to socialize. We can use Google Docs to collaborate on engagement materials and content.

Based on the changelog, @jpmckinney suggested the following:

• planning process vs contracting process Clarify contracting process, record and ocid, define planning process (866) #1216
• stages Update stage object descriptions, release tags and planning process description #1415, award Update definition of award #1175, contract Clarify contracts description (896) #1208
• buyer Deprecate 'funder' and update buyer description in partyRole #1182 vs procuring entity Improving the description of procuringEntity #1163
• status codelists Update all status codelists #1160 Add termination codes to contractStatus #1201
• framework agreements Clarify contracts description (896) #1208 schema: Include submission terms extension and definition in the submissionMethodDetails description #1442
• new norms String identifiers preference #1086 Strengthen some normative statements in schema #1112 schema: Include release date uniqueness definition in its description #1443 (there may be more)
• deprecations (and any new alternatives)

Previously, we'd also logged:

• Whether to deprecate countryName or not Add country field to Address. Deprecate countryName. #1372, depending on how common it is for a system to allow free-text for countries.

[odscjen]

Suggest also

• Project and Location extensions merging into the core schema/: merge Project and Location extensions #1684
• Update to value object: new description and amountNet and amountGross adding amountNet and amountGross to value, updating value definition #1519

[odscjen]

As an initial suggestion for how we should tackle this how about we:

1. Create a "Guide to changes in OCDS 1.2" section to detail all of the changes to be added to the main website at the highest level, i.e. the same level as "Guidance", "Reference" etc
2. Within in this group the changes by their type, e.g. deprecations, language/concept clarifications, new fields, new norms, etc giving each type it's own page
3. Create examples that demonstrate what a fictional notice would look like if modelled in OCDS 1.1.5 vs what it would look like modelled in OCDS 1.2, e.g. show the 2 side-by-side highlighting the differences - we could utilise some of the examples that already exist for OCDS 1.1.5.

This would have the benefit of enabling publishers who are switching to 1.2 to find the key differences in one place with appropriate explanation, and it would be in similar formatting to the rest of the docs. As it's all together it also means it can eventually be removed once enough publishers have made the switch to 1.2? But it might also be a bit overwhelming having it all presented as one big piece?

Alternatively we could:

1. add a "Change from OCDS 1.1.5" explanatory box to each of the relevant sections in the "Guidance" and "Reference" pages
2. still create side by side examples showing how the difference works in practice

This would have the benefit of publishers seeing the bits they need if they were checking the docs for help with a particular field/object/stage and not being overwhelmed with changes that don't affect them. But it's also a bit hidden and would require a user to review the entire docs to find all the changes guidance.

So maybe a combination of the 2 above options would be good:

1. a summary "Guide to changes in OCDS 1.2" page at the top level of the docs that links out to
2. "Change for OCDS 1.1.5" detailed explanatory boxes including where appropriate examples located in the relevant sections in the guidance

@jpmckinney @yolile what do you think?

EDIT: which ever way we go this update to the docs could be supplemented with a number of blog posts?

[jpmckinney]

Project and Location extensions merging into the core #1684

Maybe cover all the merged extensions at once.

---

For in-context notice of changes, the proposal is to use very brief versionadded and versionchanged admonitions #862 (which are already present in some places) to flag something as new, changed or deprecated. For in-context changes, our goal is only to notify, not to explain how to migrate. This is how pretty much all other documentation does things (mainly because, once you have even more versions, it would be a mess to explain every upgrade in-context). These admonitions should mainly appear in the Reference section. (They can maybe appear in the Guidance section, but I'm less clear where the changes are notable enough to warrant it.) If the upgrade documentation goes into more depth, the admonition can link to the relevant section of the upgrade documentation. Anyway, this piece of the work can be pursued in #862.

---

For upgrade documentation, some good patterns are used in:

• https://iatistandard.org/en/iati-standard/upgrades/upgrade-changelogs/integer-upgrade-to-2-01/ (see the headlines and migrating links)
• https://docs.python.org/release/3.12.0/whatsnew/3.10.html with a bullet list of highlights, sections for major changes with examples, and then everything else as a bullet list in a logical order (we might defer to the changelog for this last part – if some updates are not important enough to have their own section, but important enough to note, maybe we have a shortlist of notable changelog entries)

This page would appear under History. It should all be on one page. The goal is to be succinct. After all, the current 1.2 text can be read in the rest of the documentation. The goal of upgrade documentation is limited to questions that aren't answered elsewhere like: what's changed, who does this change affect, why was the change made (if not already self-evident from reading what's changed), an example if necessary.

---

All that said, this issue is related to the peer review step of the governance process. We expect we'll invite some specific community members to do a full review, but for the wider, open process, we will want some engagement materials (slides, etc.) to go over the key changes.

So, for this issue, it is not yet about documenting "how to upgrade". For peer review, the goal is rough consensus, and so more room can be given to "why was the change made" (what issue is being solved). Examples are also more important, because it is much easier to grasp a change during a presentation when the change is shown visually (when people can consume information at their own pace while reading documentation, it's not necessary to have visual supports for simple changes).

This issue is about key changes, so it would not be comprehensive. We're currently at 10 bullet points, which can be somewhat grouped along the lines of this early blog post https://www.open-contracting.org/2020/10/27/ocds-1-2-what-well-be-working-on/ 10 seems like a good number – we can maybe add more, but probably not much more.

Linking back to our original process document as well: https://docs.google.com/document/d/1gITRwEi3cBp7Q86U_i2PO34bdQeIJsSZWRre1bNStJE/edit

[odscjen]

ah ok, I had interpreted

We can use Google Docs to collaborate on engagement materials and content.

to mean we were also as part of this issue looking at the form the engagement materials and documentation content would take hence my comment. Thanks for the link to the google doc, that helps make the ask of this issue much clearer.

So the content we'd be looking for here is a summary of the key changes that can be peer reviewed by the community prior to 1.2 being published to ensure there is consensus with the proposed changes?

Are you happy for me to start drafting some slides to explain the changes listed here?

[jpmckinney]

So the content we'd be looking for here is a summary of the key changes that can be peer reviewed by the community prior to 1.2 being published to ensure there is consensus with the proposed changes?

Yup!

The engagement materials could take different forms. Thinking through it: I don't think we had many participants join in calls in 2016 for OCDS 1.1. Slides are easy to digest, but sometimes can be time-consuming/finicky to prepare. A web page would be fine, too. We can just publish it somewhere temporary instead of in the standard docs, but we can write it in the same Markdown (e.g. you can draft it in a branch). A benefit of a web page is we can more easily reuse some of the content for the upgrade guide. Slides help force brevity, but we can aim to be brief on the web. What do you think?

---

In case useful, here is what was used in 2016 for the 1.1 upgrade:

• Short deck https://docs.google.com/presentation/d/1cfC_e2OBbm2l9cQJoCidhBVw5K06zP9-gGbGZ-USa1Q/edit
• Long deck https://docs.google.com/presentation/d/1VFy5tJ4DyYYFc_KnsI1OdyJKs81PkdRHBuI-Sr4ks8Y/edit used in a 90-min call (can share recording if needed)

For context, I also shared the folder for the OCDS 1.1 peer review phase. Once the governance process was done, we published https://www.open-contracting.org/resources/ocds-1-1-summary-note-version-upgrade/

[odscjen]

Really useful to see the slide deck from 1.1 and the review feedback process.

I think it depends on whether you think the bulk of engagement will be async or through calls. Given you recall that not many people joined the 1.1 upgrade calls we should probably go with the option that will be easiest to use in an async fashion. Slides can force brevity and provide clear chunking of material but they're not as easily searchable as a webpage. The ability to create navigation headings in a webpage that can sit on the side of the page (so always visible, not just at the top) would be really useful particularly as I can imagine that there will be various stakeholders who will be primarily interested in certain changes and not others and would appreciate the ability to jump straight to those ones without having to scroll through the rest.

A webpage obviously does allow for too many words but we can just try and aim for brevity there! The structure of the first slides in the long deck is especially clear with the old version next to the new version of the schema layout and then the question being asked about them.

So yes I think we should go for the temporary webpage hosted somewhere other than the main standard docs. Rather than draft it on a branch I'll start in a google doc and once we're in agreement at least on the structure I can transfer it to a markdown file in a branch (which also gives us time to think of where that would go).

[jpmckinney]

Sounds great! Feel free to share an early draft, e.g. with one key change or an outline.

[jpmckinney]

Tagging @ColinMaudry in here, as Colin can also help with this content – and since he has had some time away from day-to-day issues, he might have some perspective on how to communicate the changes.

[odscjen]

@jpmckinney a rough first draft showing the general layout and an example (which as I worked on it I realised was one of the trickier ones!) of how the actual content could be structured.

cc @ColinMaudry too

[jpmckinney]

Looks good to me. I left a couple comments. It is indeed a trickier one!

Let's continue to iterate one section at a time, as we'll probably find more ways to improve the pattern for each section.

@ColinMaudry feel free to take a look when you have time.

[odscjen]

@jpmckinney I've updated according to your comments on the first section and added a few more trying to cover a couple that I think will require a slightly different pattern.

[odscjen]

The guidance for connecting publications is new and while it doesn't involve any schema changes it might also be good to include here similar to how we're explaining about the new guidance on how to link planning and contracting processes?

[ColinMaudry]

@odscjen @jpmckinney Sorry, I misconfigured my git mentions and they were lost with other notifications.

Looking at the google doc and the dev doc... 🧐

[odscjen]

thanks @ColinMaudry just to note that there's a new copy that's the one that should be used for reviewing, https://docs.google.com/document/d/1QL3MN4Exj1xgZNbsVTGF3PHampB-D3i0BB9CkmfRMfg/edit

[duncandewhurst]

Moving to review in progress as the draft content linked above is with @jpmckinney to review (Slack message).

[duncandewhurst]

@jpmckinney thinking about how we can progress this whilst your review of the content is pending, were you thinking of spinning up a new Sphinx site to host the consultation materials, or shall we set up a GitHub pages repository using e.g. the Just the Docs theme?

[jpmckinney]

I'm not sure what form the materials should take. I'll probably get a better idea after reviewing the docs. I'll also need to have a conversation internally about how we intend to engage the community – depending on the format, we might want materials as slides vs website vs online document vs printable document, etc.