Review of example

[duncandewhurst]

I've started a review but only got about 1/3 of the way through the example, I'm putting my comments so far in this issue so that they aren't lost.

General comments:

• Use sentence case in headings (only capitalize first letter).
• Need to anonymize for inclusion in OCDS docs (current version fine to share with Scotland)
• Replace embedded JSON excerpts with sphinx directives to pull examples from JSON files for inclusion in OCDS docs (current version better for sharing with Scotland)

Specific comments:

• #L3 - Add link to OCDS frameworks documentation (http://standard.open-contracting.org/latest/en/implementation/related_processes)
• #L8/9 - Replace Github repo links with extension explorer links, e.g. https://extensions.open-contracting.org/en/extensions/contract_buyer/master/)
• #L24 - Explain which of the framework types listed in http://standard.open-contracting.org/latest/en/implementation/related_processes the example relates to
• #L28 - 'Setting up' -> 'Establishing' (this seems to be the terminology used in the EU/TED) please change throughout.
• #L32 - see comment below on line 132, individual bid releases should be rolled into the award release.
• #L40 - 'tender block' -> 'tender release' (I think this is what is meant)
• #L41 - Add a heading and introductory sentence to each excerpt, e.g.

Release metadata

The tender release has the following metadata.

• #L65 - Add 'buyer' to roles, per #L24
• #L69 - Add buyer property with organization reference to entry in parties array
• #L72 - Explain that for frameworks, tender value should represent the total estimated upper value of the framework
• #L93 - 'someone' -> 'a potential supplier'
• #L99 - Use example company names rather than 'Supplier X', e.g. ExampleCo, MegaCorp, BigCo etc, to avoid confusion over tenderer/supplier distinction.
• #L100 - construct parties.id using [scheme]-[identifier], per guidance in schema
• #L122 - update per previous comment
• #L132 - suggest removing this sentence unless we're aware of an example where tenderers are disclosed one by one as bids are received, or a specific use for disclosing that information piecemeal. Replace with a sentence highlighting that that bid extension can be used to disclose details of individual bids, including the date each bid was received.
• #L140 - each tenderer should have a different company number, construct identifiers per comment on line 100
• #L165 - 'When a framework is finalised' -> 'when a supplier is awarded a place on the framework' (be explicit what finalised means)
• #L228 - Remove 'For brevity, this sample shows a single award adding multiple suppliers onto the framework. Publishers seeking extra granularity may publish individual awards for each supplier's place on the contract'. From what I've seen, awards for the establishment of framework agreements do not split the value of the award by individual supplier, instead they list all suppliers on one award notice, which has a single associated award value representing the total possible value of the framework and covering all suppliers awarded a place on the framework. We might want to add a sentence to explain that.
• #L272 - 'without any further tendering process' -> 'without any further competition'

[duncandewhurst]

General points:

• Don't capitalise common nouns, e.g. 'Framework Agreement', 'Mini-competition' etc. when used in sentences

• I think it would be easier to follow if the example described what the framework was actually for, e.g 'Framework for the supply of electrical testing services' instead of 'An Example Framework' and 'Purchase of electrical testing for equipment in council head office' instead of 'The First Direct Call-Off' etc.

• Frameworks can have both multiple buyers and multiple publishers, e.g.

  • Multiple buyers, single publisher:
    • NHS Scotland runs a contracting process to establish a framework, published on PCS
    • Glasgow Royal Infirmary purchases items from the framework via a mini-competition, published on PCS
  • Multiple buyers, multiple publishers:
    • CCS runs a contracting process to establish a framework, published on Contracts Finder
    • Edinburgh City Council purchases items from the framework via a mini-competition, published on PCS

• We should be clear about which scenarios this example is addressing. At the moment I think it covers, single buyer/single publisher and multiple buyer/multiple publisher, but misses multiple buyer/single publisher, which I think might be the most common type of framework.

• It would be good to add a section under the multiple publishers heading expanding on the considerations for integrating OCDS data from different publishers/systems, off the top of my head it would need to cover:

  • ocid - to link direct calls offs to framework establishments and to link mini-competitions to framework establishments
  • award.id - to link direct calls offs to framework establishments
  • parties.id - keeping consistent between publishers
  • contracts.id - to avoid clashing contract ids for direct call-offs

Q: Should we include some guidance for data users in the example, e.g. how to answer:

• What is the total anticipated value of the framework agreement?
• Which suppliers were awarded a place on the frameworks?
• What is the total value of purchases from the framework?
• Which suppliers were awarded call-offs from the framework?

Specific points:

• #L274 - 'previous Framework Agreement' -> 'establishment of the framework agreement', 'release information' -> 'release metadata'

• #L286 - 'The contracts array is then added' -> 'An item is added to the contracts array', 'details of the contract' -> 'details of the call-off'

• #L286 - this example shows a framework with one buyer, so the buyer doesn't need to be declared on the contract object, since it will be the same for all call offs. We should also highlight that this is where the contract suppliers extension is being used.

• #L311 - suggest moving this to the beginning of the example, as Glasgow City is known as the buyer when the framework when the framework is established

• #L332 - suggest rewording to explain more fully what is repeated, "For each subsequent call-off a new item is added to the contracts array and a release is published.

• #L339 - suggest rewording, "Call-offs from a framework agreement can also be made via a mini-competition, where more than one supplier on the framework is invited to submit a bid to provide specific goods, works or services to a buyer."

• #L341 - Reword to explain why mini-competitions are modelled using separate contracting processes in OCDS: "Mini-competitions are represented in OCDS using a separate contracting process, linked to the establishment of the framework, because they involve a further competitive stage."

• #L346 - Is there an example where these extensions would be required for a mini-competition? If not, we should update this to say that the extensions aren't required for the mini-competition.

• #L348 - 'sample' -> 'example'

• #L425 - 'commissions' -> 'establishes'

• #L471 - See previous comments on bidders (#L132), tenderers would likely be populated as part of the award release.

• #L566 - 'Next the framework agreement is finalised' -> 'Suppliers are awarded a place on the framework agreement'. Also, I think 'poor supplier 4' may be a little informal for the OCDS docs :-)

• #L604 - 'set up' -> 'established'

• #L611 - I don't think we can suggest this is straightforward, due to the integrations of different publishers' systems that would need to take place.

• #L613 - release ID can be anything, as long as it doesn't clash with another release id, so I think we should avoid being too prescriptive about the structure of the release ID. We could suggest prefacing it with the ocid prefix of the publisher as an option for guaranteeing its uniqueness.

• #L666 - noting that the ids used for the suppliers would need to match between the two publisher's system.

• #L724 - good question! We'd need to think about the pro's and con's of each option from the perspective of publishers and users:

  • Create a new award for each new supplier awarded a space on the framework; or
  • Add them to the original award for the set up of the framework