Skip to content

Readability improvements to README#14

Merged
emmanuelmathot merged 9 commits into
zarr-conventions:mainfrom
kylebarron:kyle/readme-edits
May 20, 2026
Merged

Readability improvements to README#14
emmanuelmathot merged 9 commits into
zarr-conventions:mainfrom
kylebarron:kyle/readme-edits

Conversation

@kylebarron
Copy link
Copy Markdown
Contributor

@kylebarron kylebarron commented Apr 7, 2026

Changes

  • Refer to the "proj" convention by its proper name geo-proj, not proj:. proj: is the key prefix and geo-proj seems to be the proper name of the convention
  • More hyperlinks. There should be easy links to the geo-proj and multiscales conventions when we reference them.
  • Move field attributes from h4 to h3 to make their definitions more prominent
  • Change several "bolded headers" to "h4 headers". This is important because it gives an explicit anchor to these headers. So a consumer can link directly to "coordinate convention", for example
  • Move the section about "implications of using spatial:transform with multiscales" as part of the definition of spatial:transform, not the example section.

Comment thread README.md Outdated
@emmanuelmathot emmanuelmathot self-requested a review May 13, 2026 20:47
Copy link
Copy Markdown
Contributor

@emmanuelmathot emmanuelmathot left a comment

Choose a reason for hiding this comment

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

A few inline suggestions, plus two heads-ups:

  • Stale proj: convention-name references remain outside the diff hunks: line 105 (bbox description), line 348 example heading (### Composition with proj: Convention) and intro, line 452 (Note how CRS information (proj:) is separated...), and FAQ entries at lines 491, 499, 501, 503, 507, 510 -- many of these use proj: to mean the convention, not the key prefix. Worth a follow-up pass to be consistent with this PR's stated rule.
  • Likely conflicts with two open PRs touching the same sections: #11 rewrites the spatial:transform coordinate-convention / registration prose, and #24 restricts the schema and field descriptions to 2D and removes the 3D bullets in spatial:dimensions/spatial:bbox/spatial:shape. Probably easiest to land #11 and #24 first, then rebase this.

Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
@maxrjones
Copy link
Copy Markdown
Collaborator

maxrjones commented May 14, 2026

@emmanuelmathot @kylebarron would either of you have time to resolve Emmanuel's comments and sync this with the latest changes on main?

kylebarron and others added 8 commits May 19, 2026 14:37
Co-authored-by: Emmanuel Mathot <emmanuel.mathot@gmail.com>
Co-authored-by: Emmanuel Mathot <emmanuel.mathot@gmail.com>
Co-authored-by: Emmanuel Mathot <emmanuel.mathot@gmail.com>
@kylebarron
Copy link
Copy Markdown
Contributor Author

I think I've resolved all concerns and this should be good to merge

@emmanuelmathot emmanuelmathot merged commit d45f616 into zarr-conventions:main May 20, 2026
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.

3 participants