Primer feedback

[duncandewhurst]

Great to see that the Primer is live. I noticed a few issues from a quick read-through. Some are readability/copy-editing issues, some are more substantive. Happy to do a more detailed review, if that would be helpful.

https://standard.open-contracting.org/latest/en/primer/

• Paragraph 1 - the bullet points mix 'OCDS' and 'the OCDS'
• Paragraph 2 & 3 - repetition of 'detailed documentation to guide you in implementing the standard'

https://standard.open-contracting.org/latest/en/primer/what/

• Objectives - the first paragraph isn't an objective. It speaks to the main purpose of the page, to describe what OCDS is. It would be better outside of the objectives box.
• Paragraph 1 - repetition of 'Open Contracting, 'Open Data', 'Data Standard' in the first sentence and in the subsequent bullet points

https://standard.open-contracting.org/latest/en/primer/how/

• Objectives - similar issue with the first paragraph. I think it should be outside of the box.
• Diagrams - the diagrams are inconsistent. One includes the planning stage, one doesn't. This could be confusing because the text doesn't address the inconsistency. In any case, there is a lot of repetition between the diagrams, so I think one diagram would suffice to communicate both the stages of a contracting process and the purpose of the ocid.
• Paragraph 1 - the definition of a contracting process matches neither the old 1.1 definition or the new 1.2 definition from Clarify contracts description (896) #1208. It's confusing to say 'aimed at concluding one or more contracts' when the stages/diagrams include implementation.
• Paragraph 4 & 5 - repetition of 'provides a common framework'
• Paragaph 5 & 8 - repetition of 'the default format of the data is JSON'
• Paragraph 6 - typo: 'When mapping your data to the OCDS our sing OCDS data'

https://standard.open-contracting.org/latest/en/primer/releases_and_records/

• Objectives - similar issue with the first paragraph. I think it should be outside of the box.
• Diagram - the diagram only shows OCDS releases. The diagram in the draft shared with the helpdesk shows how releases are linked together in a record:
  
• Final paragraph - the first bullet is confusing because it uses 'documents' to refer to documents linked from tender/documents etc., but everywhere else on the page 'documents' refers to a release or record JSON document.

[mrshll1001]

I had a peek at this as well and have some readability feedback which shouldn't be too heavy in most parts:

https://standard.open-contracting.org/latest/en/primer/what/

There are three concepts behind the OCDS: Open Contracting, Open Data, and Data Standard.

The final point reads a bit off, as Data Standards in the abstract tends to be pluralised. In the subsequent bullet points, we also pluralise it. I would change the sentence to read "There are three concepts behind the OCDS: Open Contracting, Open Data, and Data Standards.".

Academic research shows that improved openness and transparency is good for public integrity, value for money and competition when it is linked to systemic changes that allow people to use the information

Citations needed. While we're not in academia, if we're making claims such as these we should be backing them up or it reflects poorly on us. Recommend either blog-style referencing with inline hyperlinks to papers, or IEEE style with numbered citations and a list of sources at the bottom of the page. To be clear; I don't think that all knowledge needs to be enshrined in published papers -- but if we're claiming that academic research says X, then we need to cite it.

https://standard.open-contracting.org/latest/en/primer/how/

In designing the OCDS, we explored a range of different user needs and use cases for data about public contracting

This might be one for the longer-term, but it'd be really great if this linked off to a summary or some writing about our initial research. I wasn't around when this was performed; did we communicate our findings anywhere? Again, it doesn't need to be peer-reviewed venues but if we had a section on the OCP website which states what our original research found, it'd be great to show our working and to link to it here.

https://standard.open-contracting.org/latest/en/primer/releases_and_records/

The only thing that can be truly called “OCDS data” is a JSON document that validates against the OCDS schema.

I'm wary that we've just come from the previous page where we've said that OCDS can be published via spreadsheet and tabular formats. A technical reader will likely understand this, but others may not. We do a good job on the previous page of clarifying the relationship between the JSON and tabular formats, but I think it bears summarising here (in a single sentence) if someone has jumped to this page or has been linked to it by a colleague.

[jpmckinney]

Thanks for the comments!

For Duncan's points:

• The first sentence of the objective box gives a bit of context to understand the objectives. In the case of the "what" page, that content is not repeated elsewhere, so I have moved it out of the box. For the others, that content is repeated, so it is not strictly needed outside the box. It is fine to leave it in the box where it is nearest the content it is meant to support.
• All other points are addressed in the PR. Note that Clarify contracts description (896) #1208 (concluding -> implementing) had been resolved after the Primer was drafted.

For Matt's points:

The final point reads a bit off, as Data Standards in the abstract tends to be pluralised. In the subsequent bullet points, we also pluralise it. I would change the sentence to read "There are three concepts behind the OCDS: Open Contracting, Open Data, and Data Standards.".

To accommodate Duncan's feedback, I kept the concepts in the bullets only. See the PR.

Citations needed. [...]

Added a link to https://www.open-contracting.org/impact/evidence/ which includes academic research and other evidence.

It'd be really great if this linked off to a summary or some writing about our initial research

Linked to https://www.open-contracting.org/resources/demand-side-assessment-report/

I'm wary that we've just come from the previous page where we've said that OCDS can be published via spreadsheet and tabular formats. A technical reader will likely understand this, but others may not. We do a good job on the previous page of clarifying the relationship between the JSON and tabular formats, but I think it bears summarising here (in a single sentence) if someone has jumped to this page or has been linked to it by a colleague.

The CSV format is non-normative, as it is only described in the guidance. Any effort to make it normative needs to wait for OCDS 1.2. So, it remains true that the only thing that is truly OCDS data is JSON data. I've reworded the previous page to make it clear that the Excel/CSV files are conversions of OCDS data.

Regarding a more detailed review, the Primer was tested with 10 users in English and Spanish and reviewed internally by both helpdesk teams in CRM-7157. I expect that, if there are any remaining issues or improvements to be made, then they are minor. We can instead turn our attention to making 1.2 progress and to other 1.1 issues that are more major.