Avoid examples that are incoherent, or that are too abstract

[jpmckinney]

Users prefer specific examples. We now have many specific examples on deeper pages (e.g. for the Map step).

However, much of the older content still has generic/abstract examples – or no examples.

We should review the documentation to check for examples that need to be added or improved. We can then list the pages as a to-do list in this issue, and close the issue once a sufficient number of pages have been updated.

[jpmckinney]

cc @sabahfromlondon to identify/prioritize the pages on which to add/improve examples.

[odscjen]

@jpmckinney is it ok if I start working on this or shall I leave it for Sabah?

[sabahfromlondon]

@jpmckinney I think I missed this! Sorry.

I'll compile the list this week.

Thanks for flagging @odscjen

[sabahfromlondon]

@jpmckinney I've completed a review of the documentation pages. I also thought it was worth checking the depper pages, even though that was not quite within the scope of this ticker. It didn't take much longer and I have some thoughts / suggestions it might be worth discussing..

Here's the link to the spreadsheet.

Shall we discuss on our call on Wednesday?

cc: @odscjen

[jpmckinney]

Thank you! We discussed and answered some of the questions in the sheet. I'll leave this with analysts to find appropriate examples.

[neelima-j]

The sheet has identified 2 required tasks and 9 potential tasks

Example Required

• Include a real world example of what OCDS looks like in JSON and CSV, below the green box at How does the OCDS work?
• Have real world examples of a release and record from the same dataset. Use the dropdown for the user to toggle between the two as per other pages in the documentation, at How is OCDS data published?

@jpmckinney for the 'Maybe' examples, is the sheet the best place to ask clarifying questions/ have discussions, or would you rather we brought it here as tasks?

[jpmckinney]

@neelima-j I think your first link is meant to be to https://standard.open-contracting.org/latest/en/primer/how/?

For the maybe examples, let's move it here as notifications are easier to track.

[odscjen]

Maybe examples copied in from the spreadsheet. Initial comments also from the spreadsheet, italic comments added by me as I transferred this list to here:

• Awards and contracts - The JSON example is an external link probably becuase it is long - suggestion is to leave as it. There are also tabular examples, which should also be in JSON?
• Electronic catalogs - Could be helpful, but possibly no examples for this?
• Updates and amendments - The examples look fictional, but still very easy to understand. I assume the task is to see if there are any real examples which could be used instead?
• Milestones - The examples look fictional, but still very easy to understand. Perhaps a tender milestones example could be added? Again assume the maybe is around looking for real world examples to use instead here?
• Buyers and suppliers - Example could be in JSON in addition to/instead of tabular. The example is for the Department of Health and Social Care, but UK could also be added to the description.
• Organization references - Perhaps we should change the name of the organisation in the example to a name users will recognise as a possible tenderer and then supplier e.g. Microsoft? Maybe we could add an example of how the JSON looks for multiple organisations and with different roles?
• Record reference - Real world examples are welcome here
• Merging - Real world examples are welcome here
• Identifiers - It's possible that users might want to copy what another publisher has done, so may want to look up the whole dataset i.e. via the registry so it would be good to have real world examples throughout this page

[jpmckinney]

@yolile Which of these would you prioritize for added/improved examples? Are any good enough as-is?

[yolile]

Include a real world example of what OCDS looks like in JSON and CSV, below the green box at How does the OCDS work?

We often hear and need to show partners what OCDS data looks like, so this sounds good. The only thing to consider when preparing the example is to make sure that we state that this is just an example and not all the example fields are required nor does the example contain all the existing fields etc.

Have real world examples of a release and record from the same dataset. Use the dropdown for the user to toggle between the two as per other pages in the documentation, at How is OCDS data published?

For this one, I think we have worked examples at the Merging section and the Change History guidance. Maybe we can just add a sentence saying that an example is available on the Change History page?

Awards and contracts - The JSON example is an external link probably becuase it is long - suggestion is to leave as it. There are also tabular examples, which should also be in JSON?

The tabular examples are tabular on purpose to easily demonstrate the issue and solution. I think we can leave it as it is.

Electronic catalogs - Could be helpful, but possibly no examples for this?

Leave it as it is as there is no special mapping to show

Buyers and suppliers - Example could be in JSON in addition to/instead of tabular.

Agree that the example should be in JSON and not in tabular format.

Identifiers - It's possible that users might want to copy what another publisher has done, so may want to look up the whole dataset i.e. via the registry so it would be good to have real world examples throughout this page

The identifiers section has a lot of things to be improved and it has its own issues already documented.

For all the others, do we really want/need real-world examples? I can see some value in having a real example to follow, but I'm afraid of 1) broken links in the future and 2) the reader following any bad practice that the referenced publisher might have. We could avoid both things by only adding a copy of the real JSON file but I don't see much difference with having fictional examples (other than knowing who else is publishing that in OCDS)

[jpmckinney]

@yolile When this issue was created, we had identified that users find it harder to relate to an example if it is totally fictional, e.g. "Department of Bubble Gum buys 10 blister packs of chewing gum from Happy Smiles Inc."

If our fictional examples are close enough to "real", then they are fine. If there are deficiencies in a publisher's data, we can just correct them in the documentation - we aren't making a promise that the data is identical.

Edit: Another reason for using real data was to avoid creating incoherent examples. We sometimes had such examples in the past, where we wanted to demonstrate a lot of fields at once, but it started to make no sense in reality.

[odscjen]

For the release and record of the same dataset, Ghana publish records which include versioned and compiled releases so they're a good example for this e.g use ocds-uhveoc-680235 from https://www.ghaneps.gov.gh/ocds/services/recordpackage/getrecordpackage/2023/10 which has 2 releases. However the data will need cleaned up, e.g. they're not used parties.ids correctly and we probably don't need to include all of the fields they have. This could replace the fictional example in merging and then be linked to in How is OCDS data published along with Change history as suggested by @yolile in #1449 (comment).

Ebonyi State in Nigeria could be used for the json and csv example, they provide both json and excel downloads, e.g. https://ebonyieprocure.eb.gov.ng/do_award_contract_details.php?id=ocds-zinqhl-014665-EB/WTR/EP002-NG. Again this will need corrected, e.g. id's are not being used correctly, and we'll remove some of the fields so that it's not an overly long example.

I've picked African examples for both of these as:
a) most of the current examples seem to be either from the UK, Moldova, or Latin America
b) they're both publishers that are still publishing OCDS

@jpmckinney @yolile if you're happy with those examples I'll get started on drafting them up taking into consideration the need to make it clear that the actual data may not be identical to the data the publisher has published.

Re. the other points are you happy with:

• leaving the Buyers and suppliers example as fictional as long as it's converted into json? (it seems like a coherent example to me using real companies)
• the fictional example in Milestones left as is as it looks coherent and close to real
• the fictional example in amendements also gets left as is as it looks coherent and close to real
• leaving as is the example used in Organization references as it is a real company (although a small one), I'm not sure I see the need to change it to a large multinational (although I may be biased in this particular case as ODS is the example company!)

I've updated the above comment that lists the maybes to strike out those that @yolile has already confirmed can be left as is