search

CesiumGS / 3d-tiles

Specification for streaming massive heterogeneous 3D geospatial datasets :earth_americas:
2.13k stars 469 forks source link

Consider renaming overview PDFs? #550

Closed donmccurdy closed 2 years ago

donmccurdy commented 2 years ago

When reading through next/README.md, which arguably looks a lot like an overview of 3D Tiles Next extensions, it's a bit confusing to find this link at the bottom of the page:

The 3D Tiles Next Overview is an overview of the new extensions that are introduced with 3D Tiles Next.

In Khronos terminology these are "Reference Guides" or "Reference Cards", I wonder if we should adopt similar naming here? See: https://www.khronos.org/developers/reference-cards/. I was trying to come up with a better way to differentiate the overview wording, like "an overview with more detail than this overview but less detail than the specifications", but didn't get very far with that. :)

GatorScott commented 2 years ago

FWIW, Slideshare access is denied at my workplace. I like the terminology though and should support testing the ideas. The specification from which prototype implementations can be developed and tested will be the real test.

lilleyse commented 2 years ago

+1 for "Reference Card" - that's the terminology I would normally use. The blog post says "overview reference card"

javagl commented 2 years ago

The naming is probably an artifact of https://github.com/javagl/gltfOverview , even though it is also called a "Reference Card" on the Khronos site now. I had/have some concerns about calling it a "Reference Card", because that sounds very formal and normative (as in "the reference"), even though these overviews usually (intentionally) don't go down to the same level of details as the actual spec.

I can rename the file and directory to reference-card, if this is the consensus. (I assume that this should also refer to the original 3D Tiles overview, not only the 3D Tiles Next one).

donmccurdy commented 2 years ago

The Khronos terminology is not totally consistent either, e.g. if you open the glTF card its title is "Quick Reference Guide". I'm not aware that use of the term "Reference" there has gotten confused with the specification, but the term "Quick" might help to offset that confusion too.

javagl commented 2 years ago

I'd create a PR then, renaming the directories from overview to reference-card, and refer to it as "reference card" in the texts.

(Or maybe as "quick reference card" where appropriate, as a subtle disclaimer that this is not an extensive, specification-level reference card like https://www.khronos.org/files/opencl30-reference-guide.pdf or so...).

@shehzan10 I'd also rename the 3D Tiles (non-Next) overview accordingly, if this is OK for you, just to be consistent.

javagl commented 2 years ago

An aside, @GatorScott

FWIW, Slideshare access is denied at my workplace.

I assume that refers to the links at https://www.khronos.org/developers/reference-cards/ . But you should be able to select an entry from the "Free PDFs" dropdown menus, and access the PDFs directly (that might be easily overlooked).