remove mention of building blocks and blocks from documentation #1660
Conversation
There was a problem hiding this comment.
I think the style guide needs updating to reflect the agreement in #1347, my understanding of which is that we should use 'sub-schema' when referring to the definitions in the schema and 'object' when referring to their representation in data. That aligns with the sentence that appears at the start of the sub-schema reference in OC4IDS, which explains the relationship between sub-schemas and objects.
Most of my suggested changes are based on that understanding, except where I've suggested replacing 'object' with 'array' in order to align with the types in the schema.
|
There are two occurrences in documentType.csv (subContract, billOfQuantity) where we can just delete the last clause. If those aren't handled by other PRs or issues, let's fix them here. Noting that use of "block" on two occasions in the Milestone sub-schema will be fixed by #850 |
|
I've removed the final sentences from both of those codes in documentType as I don't they were being picked up anywhere else |
There was a problem hiding this comment.
I started reviewing, but having now read more content using the different available terms, I think we should prefer "field", unless the word "object" or "array" is contributing to the understanding of the sentence. Can you review with that in mind?
We can update the handbook accordingly.
|
added an issue to the handbook repo to update the style guide open-contracting/standard-development-handbook#285 |
Co-authored-by: James McKinney <[email protected]>
|
@jpmckinney are you ok with the suggestions in open-contracting/standard-development-handbook#285 (comment), if so I'll redo this PR with those all in mind |
|
|
||
| ### Amendment | ||
|
|
||
| A release may amend values from a previous release. Whilst the release & record model of OCDS offers the opportunity to keep a full versioned history of changes, in many cases it is important for changes to a tender, award or contract to be explicitly declared. | ||
|
|
||
| The amendment array in a tender, award or contract block provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. | ||
| The `amendments` array in a `tender`, `Award` or `Contract` object provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. Each amendment is detailed using the `Amendment` subschema. |
There was a problem hiding this comment.
| The `amendments` array in a `tender`, `Award` or `Contract` object provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. Each amendment is detailed using the `Amendment` subschema. | |
| The `amendments` array in a `tender`, `Award` or `Contract` object provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. |
There was a problem hiding this comment.
again I think this is useful to link the subschema that will populate the array
| @@ -605,15 +611,15 @@ The items block is used to list the line-items associated with a tender, award o | |||
|
|
|||
| ### Milestone | |||
|
|
|||
| Milestone information can be included in the [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) blocks. | |||
| Milestone information can be included in the [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) objects. | |||
There was a problem hiding this comment.
| Milestone information can be included in the [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) objects. | |
| Milestone information can be included in [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) objects. |
There was a problem hiding this comment.
I think the 'the' is needed, if it was just one thing in the list "Milestone information can be included in planning object" wouldn't be right, it needs the "the"
There was a problem hiding this comment.
Hmm, I'm not a grammar expert, but if there was one thing in the list I think the sentence would be "Milestone information can be included in planning objects" because we're not talking about a specific instance of a planning object, rather we're talking about planning objects in general.
There was a problem hiding this comment.
well out of the three of us I suspect @jpmckinney is the grammar expert so I'll leave it to him in his review :)
| @@ -669,10 +675,10 @@ In OCDS each contracting process can have only one tender stage. There are a num | |||
|
|
|||
| * When one planning process results in many tenders; | |||
| * When a contract is awarded following two distinct, but related, tender processes, such as in national frameworks with locally run mini-competitions; | |||
| * When a contract results in the award of sub-contracts - and those sub-contracts are also tracked using OCDS; | |||
| * When a contract results in the award of subcontracts - and those subcontracts are also tracked using OCDS; | |||
There was a problem hiding this comment.
The RelatedProcess reference needs updating per #1713 so I haven't reviewed the changes here.
Co-authored-by: Duncan Dewhurst <[email protected]>
closes #1347
Used primarily "objects" as per the section of the style guide that states
but did use "sub-schema" in a few instances.
There's 2 uses of "block" in the schema itself but they'll be covered by a PR for #850