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

remove mention of building blocks and blocks from documentation #1660

Open
wants to merge 16 commits into
base: 1.2-dev
Choose a base branch
from

Conversation

odscjen
Copy link
Contributor

@odscjen odscjen commented Nov 17, 2023

closes #1347

Used primarily "objects" as per the section of the style guide that states

When describing JSON schema * “object”, not “block”

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

Copy link
Contributor

@duncandewhurst duncandewhurst left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

docs/guidance/build/merging.md Outdated Show resolved Hide resolved
docs/guidance/map/amendments.md Outdated Show resolved Hide resolved
docs/guidance/map/amendments.md Outdated Show resolved Hide resolved
docs/guidance/map/amendments.md Outdated Show resolved Hide resolved
docs/guidance/map/amendments.md Outdated Show resolved Hide resolved
docs/schema/reference.md Outdated Show resolved Hide resolved
docs/schema/reference.md Outdated Show resolved Hide resolved
docs/schema/reference.md Outdated Show resolved Hide resolved
docs/schema/index.md Outdated Show resolved Hide resolved
docs/guidance/map/extensions.md Outdated Show resolved Hide resolved
@jpmckinney
Copy link
Member

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

@odscjen
Copy link
Contributor Author

odscjen commented Dec 7, 2023

I've removed the final sentences from both of those codes in documentType as I don't they were being picked up anywhere else

Copy link
Member

@jpmckinney jpmckinney left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

docs/guidance/map/organization_classifications.md Outdated Show resolved Hide resolved
docs/guidance/map/organization_personal_identifiers.md Outdated Show resolved Hide resolved
docs/guidance/map/organizational_units.md Outdated Show resolved Hide resolved
docs/guidance/map/organizational_units.md Outdated Show resolved Hide resolved
@odscjen
Copy link
Contributor Author

odscjen commented Dec 15, 2023

added an issue to the handbook repo to update the style guide open-contracting/standard-development-handbook#285

Co-authored-by: James McKinney <26463+jpmckinney@users.noreply.github.com>
@odscjen
Copy link
Contributor Author

odscjen commented Jan 9, 2024

@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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Eliminate language of "building blocks"
3 participants