Improve packaging documentation

[jpmckinney]

We introduce the concept of releases and records on one page, and we briefly talk about how to package them halfway down another page. There's also some discussion of APIs. This is insufficient, based on common errors and questions we receive.

I intend to do a full audit of the documentation at a later date, but my initial thoughts on this specific issue is that the current documentation expects the reader to proceed linearly through the "getting started" section, reading everything. We know that this is not how many people approach the documentation.

One potential solution is to author a new page (reusing existing content as applicable), which describes:

1. A release (the fundamental and first thing a publisher will produce)
2. A release package, and the various reasons/processes/patterns for which a publisher might want to package releases (i.e. when/why you would want to use a release package)
3. A record, and how it relates to releases
4. A record package, hitting the same points as for a release package

My anecdotal evidence is that fewer publishers use records/record packages that we would anticipate, especially considering that a record is an important concept (I think all publishers should have records). We aren't communicating these concepts clearly enough, and I think a stepped approach as above that more closely matches the incremental implementation of OCDS would better serve publishers.

[timgdavies]

Agreed. I think more worked examples, and some really good documentation design can help us here to better communicate the key points.

[jpmckinney]

Documenting a couple possible patterns to include in the documentation:

1. If a publisher intends to provide a single bulk download of all releases, they should publish a single release package containing all the releases.
2. If a publisher intends to provide a single bulk download of all releases organized by contracting process, they should publish a single record package containing one record per contracting process, with each record containing all the releases for that contracting process.

We can provide sample JSON to illustrate each pattern.

[jpmckinney]

cc @juanpane

[jpmckinney]

Related: #389

[duncandewhurst]

I added a related issue on how the package schemas are structured: #716

My anecdotal evidence is that fewer publishers use records/record packages that we would anticipate, especially considering that a record is an important concept (I think all publishers should have records). We aren't communicating these concepts clearly enough, and I think a stepped approach as above that more closely matches the incremental implementation of OCDS would better serve publishers.

I agree with this but it's worth noting that not all publishers can have records.

When OCDS data is created on the fly (i.e. when a user requests it) and isn't stored independently of the non-OCDS data which it is generated from, then it's not possible to publish a record, because a record must contain an array of all the existing releases related to the contracting process and only one release can exist at once in this model. This is quite a common model for OCDS publishers.

As long as the release ID is updated whenever anything changes in the underlying data, then a 3rd party can regularly scrape the data, store each release and publish records.

[duncandewhurst]

In the new documentation we should highlight that publishing release packages (rather than some other package format, e.g. a list of release) is important so that tools that work with records know what format to expect when fetching linked releases.