Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Style Guide: Add rules on the use of articles in descriptions #1406

Closed
JachymHercher opened this issue Aug 29, 2021 · 6 comments
Closed

Style Guide: Add rules on the use of articles in descriptions #1406

JachymHercher opened this issue Aug 29, 2021 · 6 comments
Labels
Focus - Documentation Includes corrections, clarifications, new guidance, and UI/UX issues quick
Milestone

Comments

@JachymHercher
Copy link
Contributor

If I'm not mistaken, https://ocds-standard-development-handbook.readthedocs.io/en/latest/meta/index.html does not give rules on the use of definite/indefinite/no articles in field and code descriptions. The standard seems to use them sometimes inconsistently, so it would be useful to have them.

@JachymHercher JachymHercher added Focus - Documentation Includes corrections, clarifications, new guidance, and UI/UX issues quick labels Aug 29, 2021
@jpmckinney
Copy link
Member

I guess there are two issues: coming up with the rule, and then applying it. What rule do you suggest?

@jpmckinney
Copy link
Member

Moving to 1.2 since we can't change field and code description without a new release, and no new release is scheduled for 1.1

@JachymHercher
Copy link
Contributor Author

JachymHercher commented Sep 17, 2021

In eForms, articles depend on the data. Specifically:

  • Business groups that only contain other fields have no article (and typically start "Information about...")
  • Fields that can have multiple values start with "A"
  • Fields that can only have a single value start with "The", except those that are booleans which start with "Whether".

We could do it along the same lines for OCDS?

@jpmckinney
Copy link
Member

For fields with multiple values, I think we currently often use "The" but with a plural noun phrase. However, if the value is an array of objects, then the object's description typically uses "A"/"An". A special case is tag, which has weak semantics, so it's "One or more values from the closed releaseTag codelist".

I've made this and other changes in this commit: open-contracting/standard-development-handbook@3fd619f

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

@jpmckinney jpmckinney added this to the 1.2.0 milestone Dec 8, 2022
@duncandewhurst
Copy link
Contributor

duncandewhurst commented Jun 18, 2023

Is the task here to go through the field descriptions and apply the updated style guide?

Edit: Related issue #850

@jpmckinney
Copy link
Member

Closing as this issue is now a subset of #850.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Focus - Documentation Includes corrections, clarifications, new guidance, and UI/UX issues quick
Projects
Status: Done
Development

No branches or pull requests

3 participants