Address Primer feedback

docs/guidance/build/serialization.md

@@ -22,7 +22,7 @@ Most programming languages provide tools for output data as JSON.
 
 Most programming languages provide tools for reading JSON.
 
-A number of [JSON native databases](https://en.wikipedia.org/wiki/NoSQL) are available for working directly with large collections of JSON documents, and command line tools such as [jq](https://stedolan.github.io/jq/) support advanced query and data retrieval with JSON files.
+A number of [JSON native databases](https://en.wikipedia.org/wiki/NoSQL) are available for working directly with large collections of JSON texts, and command line tools such as [jq](https://stedolan.github.io/jq/) support advanced query and data retrieval with JSON files.
 
 There are also a range of generic tools which can convert JSON into flat CSV structures, including:
 

docs/index.md

@@ -10,14 +10,14 @@ Governments around the world spend an estimated [US$13 trillion](https://www.ope
 
 The Open Contracting Data Standard (OCDS) enables disclosure of data and documents at all stages of the contracting process by defining a common data model. It was created to support organizations to increase contracting transparency, and allow deeper analysis of contracting data by a wide range of users.
 
-The OCDS is made up of several parts, designed to help you use OCDS effectively.
+The OCDS documentation is made up of several parts, designed to help you use the OCDS effectively.
 
 * [Primer](primer/index): Introducing the key concepts and features of the OCDS
 * [Guidance](../guidance/index): Step-by-step instructions on how to design and implement an OCDS publication, including practical examples
 * [Reference](../schema/index): The OCDS data model (schemas, codelists and validation rules) as well as specific rules that need to be followed to publish OCDS data
-* [Getting help](../support/index): How you can get Helpdesk support, tools that can help you use OCDS, and how you can participate in the OCDS community
+* [Getting help](../support/index): How you can get Helpdesk support, tools that can help you use the OCDS, and how you can participate in the OCDS community
 * [History](../history/index): Information about the changes in each version of the OCDS
-* [Data Review Tool](https://standard.open-contracting.org/review/): A tool to help check whether your data is following the OCDS correctly.
+* [Data Review Tool](https://standard.open-contracting.org/review/): A tool to help check whether your data is following the OCDS correctly
 
 The Open Contracting Data Standard is a core product of the [Open Contracting Partnership](https://www.open-contracting.org/) (OCP). If you are interested to learn more about Open Contracting advocacy and how it can be used to support wider reform and measurable improvements in public contracting, please visit www.open-contracting.org.
 

docs/primer/how.md

@@ -14,7 +14,7 @@ The Open Contracting Data Standards (OCDS) is designed to support publishing dat
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/Ibq0vEmDDzQ" title="Diving in to OCDS specifics" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 </div>
 
-The OCDS defines a unique contracting process as all the actions aimed at concluding one or more contracts. An individual contracting process has several different stages: **tendering, awarding, contracting** and **implementation.** The OCDS describes a way to model and publish data in a standardized way along entire public contracting processes.
+The OCDS defines a unique contracting process as all the actions aimed at implementing one or more contracts. An individual contracting process has several different stages: **tendering, awarding, contracting** and **implementation.** The OCDS describes a way to model and publish data in a standardized way along entire public contracting processes.
 
 <div style="width:100%">
 
@@ -77,17 +77,15 @@ Completion or Termination info
 
 <br clear="all"/>
 
-The OCDS brings together the data published at each stage using a single open contracting process identifier: the **OCID.** An OCID is composed of a prefix [registered by the publisher with OCP](../guidance/build.md#register-an-ocid-prefix), and a unique process identifier chosen by the publisher.
-
-![ocid](../_static/png/ocid_en.png)
+The OCDS brings together the data published at each stage using a single open contracting process identifier: the **OCID.** An OCID is composed of a prefix, [registered by the publisher with OCP](../guidance/build.md#register-an-ocid-prefix), and a unique process identifier chosen by the publisher.
 
 The OCID helps users to join up data across the whole contracting process – a key feature and benefit of publishing and using OCDS data.
 
-In designing the OCDS, we explored a range of different user needs and use cases for data about public contracting. Each use case has different data needs in terms of data fields, documents, publication frequency, and data quality. The OCDS provides a common framework to maximize the number of user needs that can be met through data and document disclosure.
+In designing the OCDS, we [explored](https://www.open-contracting.org/resources/demand-side-assessment-report/) a range of different user needs and use cases for data about public contracting. Each use case has different data needs in terms of data fields, documents, publication frequency, and data quality. The OCDS provides a common framework to maximize the number of user needs that can be met through data and document disclosure.
 
-The OCDS provides a common framework, in addition to the OCID, through the OCDS **schema.** The schema sets out the fields, structure, data types and validation rules for OCDS data. The schema is described using JSON Schema, and the default format of the data is JSON (JavaScript Object Notation). The schema is documented in the [Reference](../schema/index) section of the OCDS.
+In addition to the OCID, another component of OCDS' common framework is the OCDS **schema.** The schema sets out the fields, structure, data types and validation rules for OCDS data. The schema is described using JSON Schema, and the default format of the data is JSON (JavaScript Object Notation). The schema is documented in the [Reference](../schema/index) section of the OCDS.
 
-When mapping your data to the OCDS our sing OCDS data, you will encounter a number of common data fields and structures, which are described by the schema:
+When mapping your data to the OCDS or when using OCDS data, you will encounter a number of common data fields and structures, which are described by the schema:
 
 * **release metadata** - contextual information about each release of data;
 * **parties** - information about the organizations and participants in the contracting process;
@@ -99,12 +97,12 @@ When mapping your data to the OCDS our sing OCDS data, you will encounter a numb
 
 Some schema fields refer to [codelists](../schema/codelists), to limit and standardize the possible values of the fields, in order to promote data interoperability.
 
-When you publish OCDS data, the default format of the data is JSON. In addition to JSON format, OCDS can be published as Excel and CSV (comma-separated values) files.
+In addition to the default format of JSON, you can convert and publish your OCDS data as Excel and CSV (comma-separated values) files.
 
 ```{admonition} Publication formats: JSON and Excel/CSV
 :class: hint
 
-While the OCDS schema is described using JSON Schema, OCDS data can be published in both JSON format and in tabular formats such as CSV files or spreadsheets. JSON is favored by developers because it uses human-readable text to exchange complex information, such as nested objects. It can contain large volumes of information and is particularly good at handling one-to-many relationships (such as multiple bids per tender notice).
+While the OCDS schema is described using JSON Schema, OCDS data can be converted from its JSON format to tabular formats such as CSV files or spreadsheets. JSON is favored by developers because it uses human-readable text to exchange complex information, such as nested objects. It can contain large volumes of information and is particularly good at handling one-to-many relationships (such as multiple bids per tender notice).
 
 Tabular formats, such as CSV (or comma separated values) are commonly used in spreadsheets applications and other analysis tools. Many people are comfortable working with spreadsheets using tools like Excel. While JSON is the default format, a good publication will publish tabular formats as well both so that more users’ needs can be satisfied.
 ```
@@ -117,7 +115,7 @@ No matter what type of contracting data you are working with or format you publi
 * Check the structure, format and quality of your data against the OCDS schema
 
 ```{note}
-**To learn more,** go to the next page in the primer: [How is OCDS data published?](releases_and_records) You can also review the further resources below to go deeper into the subjects introduced on this page.
+**To learn more,** go to the next page in the Primer: [How is OCDS data published?](releases_and_records) You can also review the further resources below to go deeper into the subjects introduced on this page.
 
 * [Guidance to implementing OCDS](../guidance/index)
 * [Video Learning Guide to the OCDS](https://www.youtube.com/playlist?list=PL7sSifLpWd8hLOVrNMiwNApXAsOr06E1Q)

docs/primer/index.md

@@ -8,24 +8,22 @@ This Primer to the Open Contracting Data Standard (OCDS) will help you get start
 
 In this Primer, you will find resources to help you answer these questions:
 
-* [What is OCDS and why use it?](what)
+* [What is the OCDS and why use it?](what)
 * [How does the OCDS work?](how)
 * [How is OCDS data published?](releases_and_records)
 * [How can I implement the OCDS?](next)
 
-Beyond the Primer, the OCDS provides detailed documentation to guide you in implementing the standard. It provides you with access to the [authoritative version](../schema/index) of the data standard, [guidance](../guidance/index) on data publication, and other relevant resources.
+Beyond the Primer, you can use the following resources contained in the OCDS documentation to help you implement the OCDS. The remainder of the documentation covers:
 
-The OCDS also provides tools and detailed documentation to guide you in implementing the standard. The OCDS documentation includes several sections:
-
-* [Guidance](../guidance/index): Step-by-step instructions on how to design and implement an OCDS publication, including practical examples
-* [Reference](../schema/index): The OCDS data model (schemas, codelists and validation rules) as well as specific rules that need to be followed to publish OCDS data
-* [Getting help](../support/index): How you can get Helpdesk support, tools that can help you use OCDS, and how you can participate in the OCDS community
-* [Governance](../governance/index): Details about the stewardships, development, and revisions process for OCDS
+* [Guidance](../guidance/index): Step-by-step instructions on how to design and implement an OCDS publication, including helpful tools and examples
+* [Reference](../schema/index): Describing the specific rules that need to be followed to publish OCDS data
+* [Getting help](../support/index): Outlining how you can get Helpdesk support and how you can participate in the OCDS community
+* [Governance](../governance/index): Details about the stewardships, development, and revisions process for the OCDS
 * [History](../history/index): Information about the changes in each version of the OCDS
-* [Data Review Tool](https://standard.open-contracting.org/review/): A tool to help check whether your data is following the OCDS correctly.
+* [Data Review Tool](https://standard.open-contracting.org/review/): A tool to help check whether your data is following the OCDS correctly
 
 ```{note}
-**To learn more about the OCDS,** go to the next page in the primer: [What is OCDS and why use it?](what) To learn more about open contracting in general, go to:
+**To learn more about the OCDS,** go to the next page in the primer: [What is the OCDS and why use it?](what) To learn more about open contracting in general, go to:
 
 * [OCP Website](https://www.open-contracting.org/)
 * [OCP Learning](https://www.open-contracting.org/learn/)

docs/primer/next.md

@@ -3,20 +3,20 @@
 ```{admonition} Objectives
 :class: note
 
-To implement the Open Contracting Data Standard (OCDS) you should follow the steps in the implementation guidance and rules in the reference section. This page will:
+To implement the Open Contracting Data Standard (OCDS) you should follow the steps in the implementation guidance and the rules in the reference section. This page will:
 
-* Outline next steps you can follow to start implementing OCDS documentation
-* Direct you to resources for getting help on implementing OCDS
+* Outline next steps you can follow to start implementing the OCDS
+* Direct you to resources for getting help on implementing the OCDS
 ```
 
 Beyond the Primer, you can use the following resources contained in the OCDS documentation to help you implement the OCDS. The remainder of the documentation covers:
 
 * [Guidance](../guidance/index): Step-by-step instructions on how to design and implement an OCDS publication, including helpful tools and examples
 * [Reference](../schema/index): Describing the specific rules that need to be followed to publish OCDS data
 * [Getting help](../support/index): Outlining how you can get Helpdesk support and how you can participate in the OCDS community
-* [Governance](../governance/index): Details about the stewardships, development, and revisions process for OCDS
+* [Governance](../governance/index): Details about the stewardships, development, and revisions process for the OCDS
 * [History](../history/index): Information about the changes in each version of the OCDS
-* [Data Review Tool](https://standard.open-contracting.org/review/): A tool to help check whether your data is following the OCDS correctly.
+* [Data Review Tool](https://standard.open-contracting.org/review/): A tool to help check whether your data is following the OCDS correctly
 
 **Have a question? Ask us!**
 

docs/primer/releases_and_records.md

@@ -3,7 +3,7 @@
 ```{admonition} Objectives
 :class: note
 
-Open Contracting Data Standard (OCDS) data is published and updated over time using two JSON document types: “releases” and “records”.  This page will:
+Open Contracting Data Standard (OCDS) data is published and updated over time using two types of JSON data: “releases” and “records.” This page will:
 
 * Outline the purpose of releases and records
 * Describe how to publish a change history using releases and records
@@ -14,34 +14,32 @@ Open Contracting Data Standard (OCDS) data is published and updated over time us
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/OeDCLMWlY_U" title="Introducing releases and records" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 </div>
 
-The only thing that can be truly called “OCDS data” is a JSON document that validates against the OCDS schema. The JSON documents that OCDS uses are called “releases” and “records.”
+The only thing that can be truly called “OCDS data” is JSON data that validates against the OCDS schema. There are two schemas for OCDS data: “releases” and “records.”
 
 OCDS publishers are encouraged to use releases and records to publish data in near real-time and to provide a change history. Tracking change over time is important to users of contracting data because there can be many changes in the life of a contracting process. Knowing how and when certain attributes have changed can help users to understand the process, identify inefficiencies, and spot red flags for corruption.
 
-**Releases** are JSON documents that are published each time there is a change to a contracting process. Releases follow the OCDS [release schema](../schema/reference) and contain an OCID to identify the contracting process they relate to.
+A **release** is JSON data that is published each time there is a change to a contracting process. Releases follow the OCDS [release schema](../schema/reference) and contain an OCID to identify the contracting process they relate to.
 
 Releases are immutable, which means they cannot be changed once published. There can be many releases per contracting process and the collection of releases for a contracting process constitutes its change history.
 
-**Records** are JSON documents that act as an index of all releases for a single contracting process. While releases are never updated, records are updated each time there is a change to a contracting process by adding a new release to this index. Records follow the OCDS [record schema](../schema/records_reference) and, in addition to the release index, can also contain:
+A **record** is JSON data that acts as an index of all releases for a single contracting process. While releases are never updated, records are updated each time there is a change to a contracting process by adding a new release to this index. Records follow the OCDS [record schema](../schema/records_reference) and, in addition to the release index, can also contain:
 
 * A **compiled release,** which follows the same structure as a release and provides the latest value of each field. The compiled release makes it easy for users to get the latest version of the data about a contracting process.
 * A **versioned release,** which contains a history of changes for each field and allows users to see how a particular field has changed over time.
 
 Each time a new release is published it is added to the index, the compiled release is updated with the latest values, and the versioned release is updated with any new changes.
 
-![Contracting Process with releases](../_static/png/changehistory_process2.png)
+![A contracting process is described by many releases, which are aggregated into a single record](../_static/png/changehistory_process_record.png)
 
 Records and releases each contain several fields which can be used in different sections. The OCDS schema sets out the fields that ought to be included in each section (where applicable), aiming to reuse simple structures to represent information. For example, a release may contain information about items being procured. OCDS’ schema sets out standard building blocks for items across releases, including the name of the item, a description, each item’s value, and the currency used.
 
 When you publish OCDS releases and records, you are encouraged to:
 
-* Ensure all documents referenced in OCDS releases are available online
 * Publish each release and record at its own persistent URL
 * Produce bulk packages of releases and records for users to download
-* Publish versions of the data for users to access in CSV for Excel formats
 
 ```{note}
-**To learn more,** go to the next page in the primer: [How can I implement the OCDS?](next) You can also review the further resources below to go deeper into the subjects introduced on this page.
+**To learn more,** go to the next page in the Primer: [How can I implement the OCDS?](next) You can also review the further resources below to go deeper into the subjects introduced on this page.
 
 * [OCP Learning: Publishing OCDS Data](https://www.open-contracting.org/learn/publish/)
 * [Video Learning Guide to the OCDS](https://www.youtube.com/playlist?list=PL7sSifLpWd8hLOVrNMiwNApXAsOr06E1Q)