1449 improve examples

[odscjen]

Addresses #1449

Added realworld example to primer/how.md taking altered version from Ebonyi State as agreed in the issue.

Swapped out fictional example in guidance/build/merging.md for a corrected version of a real example from Ghana.

Added reference to merging and change history examples to primer/release_records.md.

Converted example in guidance/map/buyers_suppliers.md to JSON from csv as agreed.

Haven't done anything to the Identifiers section as it is being dealt with separately.

[odscjen]

@jpmckinney in updating the examples I'm getting the above test errors which appear to be looking for a specific date which was in the fictional example but not in the new real-world example. Could you please update the test to remove the need to this particular date to appear, unless there is a reason why it's needed?

[jpmckinney]

This test is one you can edit in this repository at test_docs.py. The test is checking whether the dropdown used to switch between examples works. It tries to find text that appears in one example but not the other. You can use any string within those examples that isn't expected to change in the future.

[duncandewhurst]

@jpmckinney I'm interested to know what you think of my suggestions in #1661 (comment), #1661 (comment) and #1661 (comment). After reviewing this PR, I think that most of the JSON files featured in (existing) examples in the OCDS documentation are way too long and would better serve readers' needs if we cut the fields right down to those needed to illustrate the specific examples that they feature in. That would also make the examples much easier to maintain when the schema changes.

[jpmckinney]

Yes, we should have minimal (but coherent) examples.

The purpose of #1449 is to avoid examples that are incoherent, or that are too abstract (e.g. Anytown buys widgets).

The means we agreed on was to base examples on real data.

That said, we don't care at all about matching a real existing release, as expressed in #1449 (comment)

[duncandewhurst]

Great. Shall we expand the scope of this PR to cover making the examples minimal?

[jpmckinney]

Yes, let's do it in one shot.

[jpmckinney]

Or do you mean examples not already edited by this PR? I think let's just get the examples touched by this PR done.

We can open a new PR or issue for others.

[odscjen]

@duncandewhurst I've cut down the examples a lot, let me know if you think even more could be trimmed without making the examples feel fake

[duncandewhurst]

@jpmckinney this PR is ready for your review. I've updated the examples it touches in keeping with the discussion in #1449 and #1666. I'll tackle the remainder of the examples as a part of #1666.

[jpmckinney]

Okay to merge if all suggestions merged and comments resolved.

Note that some suggestions might be hidden by GitHub and need to be expanded.

[jpmckinney]

We'll use "Squash and merge", since the commits in this PR went back and forth a bit.

[jpmckinney]

I think docs/examples/mergin/updates/merged.json is unused. It can be deleted, as well its mention in READMEmd.

I think docs/examples/change_history/tenderAmendment.json is also unused and can be deleted.

docs/examples/merging/updates/versioned.json needs to be regenerated per the readme. It's used on a couple pages, where I think the directives are fine as-is.

[duncandewhurst]

I think docs/examples/mergin/updates/merged.json is unused. It can be deleted, as well its mention in READMEmd.

I think docs/examples/change_history/tenderAmendment.json is also unused and can be deleted.

Both removed in fa9161a

docs/examples/merging/updates/versioned.json needs to be regenerated per the readme. It's used on a couple pages, where I think the directives are fine as-is.

The 'source' files no longer exist so I've instead updated the directives to reference docs/examples/amendments/tender.json, created a linked release version of the same, and made one minor update to the accompanying text.

[duncandewhurst]

@jpmckinney since my update above differs slightly from your suggestion, please let me know if you're happy for me to squash and merge.