Adopt consistent style in field and code descriptions

[jpmckinney]

The style and apparent audience (e.g. publisher or user) of descriptions in the schema is inconsistent. Compare the Tender.submissionMethod field to the 'unsuccessful' code in awardStatus.

• Update schema descriptions for common field types based on the description templates
• Update schema descriptions for other fields based on the style guide

Some codelist descriptions are explicitly normative and some are implicitly normative (compare tag to Identifier.scheme).

• Update codelist descriptions per codelist description template

[jpmckinney]

This is a bigger project, so moving to 1.2.0 (linked to #826 and #827).

[ColinMaudry]

@jpmckinney The description of this issue has not aged well as the style guide has grown significantly and field and code decriptions may have changed since then. Could you please update the issue description with updated examples of what needs fixing?

I assume this is the part of the style guide that is relevant today: https://ocds-standard-development-handbook.readthedocs.io/en/latest/meta/schema_style_guide.html#field-and-code-descriptions

[jpmckinney]

I think the same high-level issues need fixing as before. I'm sure once anyone starts on the issue after reading the style guide that they will easily find problematic field/code descriptions. Finding the issues is half the work :)

[ColinMaudry]

Wow the style guide seems to have grown a lot, great job @jpmckinney !

[duncandewhurst]

@jpmckinney is the task here basically to start the review again from the current field descriptions on 1.2-dev, but document it in a document rather than making changes directly in a PR? Or should we pull in both the 1.2-dev descriptions and descriptions from the abandoned PR (#1303)?

I'm not sure pulling both in will necessarily save any time as we'll have twice as much to read...

Edit: Noting that, depending on the answer to #1406 (comment), I think that issue can be incorporated into this one so that we don't need to go through all the field descriptions twice.

[jpmckinney]

Re: #1406, the updated guidance is at https://ocds-standard-development-handbook.readthedocs.io/en/latest/meta/schema_style_guide.html#articles

That said, the issue notes:

I figure we will need to add more as we review more descriptions.

Re: #1303, I think we'll catch the same issues it identified, so no need to pull in. Some noteworthy changes:

• Some fields had more rework
  • Identifier.scheme
  • Implementation.milestones
• Omit "(Deprecated in 1.1)" or similar from deprecated.description and from the field description.
• Remove redundant phrases like "if applicable".
• If using the nouns from a code in a sentence, use normal case (e.g. "approval letter" in Milestone.code).
• American spelling (favour -> favor).

[duncandewhurst]

Sounds good. Thanks!

[odscjen]

Starting to note the findings of the review here, I'll update this issue again once there are enough entries to be reviewed

[odscjen]

Re. Titles - there's a mix of titles with all words capitalized and those with only the first word capitalized. I'm assuming the latter is the preference from work on extensions but that doesn't appear to be specified in the style guide? @jpmckinney

[odscjen]

A general point about the style guide, there's no specific section on titles of fields. I'm finding mixtures of different patterns etc so would suggest the following:

A title should:

• Not simply repeat the description.
• Include the top-level sub-schema name it is a part of, if the field is used in more than one sub-schema.
• Only capitalize the first word of the title.

Probably other guidance will occur as I work through this

[odscjen]

I'm about half way through so if anyone wants to start reviewing my suggestions please do.

@duncandewhurst @jpmckinney

Other than the points mentioned in previous comments the only new one is that I've just skipped deprecated fields in their entirety so they may still not match the style guide and/or be inconsistent.

[jpmckinney]

Can you provide edit access to the sheet?

Makes sense to add a section on field titles to the handbook.

Only capitalize the first word of the title.

+1

Not simply repeat the description.

The description is typically written after the title, so this might be a bullet for the description. What's an example?

Include the top-level sub-schema name it is a part of, if the field is used in more than one sub-schema.

I think status, title, etc. can just be titled Status, Title, instead of Tender status, Award status, etc.

I've just skipped deprecated fields in their entirety so they may still not match the style guide and/or be inconsistent.

That's fine.

[odscjen]

Ah, sorry I thought I had, you should have edit access now.

The description is typically written after the title, so this might be a bullet for the description. What's an example?

I think what triggered this for me was award/description which has title "Description" and description "Award description". But given your response to the next point I don't think this is necessarily an issue anymore.

I think status, title, etc. can just be titled Status, Title, instead of Tender status, Award status, etc.

OK, there was inconsistency either way with some titles including the parent object name and some not so I think this needs to be included in the style guide.

[odscjen]

I'll go through and remove a load of lines from the Excel sheet where I've added the parent field to the title based on the above

[jpmckinney]

I think we should probably try to remove, as much as possible, noun phrases like "this tender" or "the tender". A tender in most places means the offer from the supplier – not the opportunity from the buyer.

However, this task is separate from style, so we should cover it in a new issue. That said, let's skip all tender fields in the review until the new issue is closed. #1639

[jpmckinney]

Ah, sorry I thought I had, you should have edit access now.

I've started to review, in two new columns.

Feel free to start an issue or PR in the handbook for any new or updated style guidance.

Note to self: I had been checking https://github.com/open-contracting/standard/pull/1303/files just in case there were some useful changes there.

[jpmckinney]

Although we aren't editing deprecated fields, let's still remove content like " (Deprecated in 1.1)" from descriptions.

[odscjen]

Noting based on the spreadsheet comments that reordering schema elements should be a seperate PR that some of these are already covered by #1382 which is on hold to avoid merge conflicts

[odscjen]

Created a new sheet to record the fields with elements in the wrong order (seems sensible to record these at the same time as going through all the fields for the descriptions and titles)

[odscjen]

scheme is described in a number of ways:

• "The list, register or system from which the identifier is taken..."
• "The scheme or codelist from which the classification code is taken..."
• "...The scheme field is used to indicate the list or register from which the identifier is taken...."
• "The list from which identifiers for units of measure are taken..."

It seems we should be using consistent language here much as we do with "goods, services and works".

I think the top option was the most recent addition, it comes from SimplyIdentifier, @jpmckinney how do you feel about using "list, register or system" as the consistent phrase?

[jpmckinney]

Yes, first one sounds good!

[odscjen]

Great, I've added those to the spreadsheet too. I think that's all of the field titles and descriptions reviewed now, I've also updated some of the suggested changes based on your initial feedback. I've indicated where I've done that with a new column I.

[odscjen]

just a gentle prod @jpmckinney that all the suggested changes are now in the spreadsheet and waiting on your review

[jpmckinney]

Yes, it's in my backlog. As this is the longest issue to review, I'll get to it in 2024.

The sheet: https://docs.google.com/spreadsheets/d/1WaN5cdU5UxoCMkq8Od5zlLj68-ckn1lnzWpt_DfzqHk/edit#gid=0

[odscjen]

Been reviewing this as there's been quite a few changes to the schema since the spreadsheet was first created. Realised the id or identifier associated with a scheme is described in a number of different ways across objects and it might be good to be consistent here, at least in the first sentence of each.

object	field	description
Classification	id	The classification code taken from the scheme. Although an integer is allowed, it is recommended to use a string.
Identifier	id	The identifier of the organization in the selected scheme. Although an integer is allowed, it is recommended to use a string.
RelatedProcess	identifier	The identifier of the related process. If the scheme is 'ocid', this must be an open contracting process identifier (ocid).
Unit	id	The identifier from the codelist referenced in the scheme field. Check the unitClassificationScheme codelist for details of how to find and use identifiers from the scheme in use.
SimpleIdentifier	id	The identifier taken from the scheme.

I think it's good to explicitly link the value in these fields to the values in the associated scheme fields. So as a consistent first sentence how about:

The identifier taken from the list, register or system referenced in the scheme field.

where the agreed common language to refer to a scheme is used as well

[odscjen]

Sorry @jpmckinney I just realised I'd not added any of the codelists to the spreadsheet! It's now a lot longer.