3D Tiles spec writing guide and extensions template

[pjcozzi]

Writing specs is hard; it requires providing both context to the reader and the most precise language (and schemas, etc.) to define a normative specification that can be implemented consistently by different developers.

We have a lot of experience and lessons learned. It would be great to centralize these into a guide and potentially an extension template/boilerplate or checklist pull request template.

Here's some notes:

• Write for the novice reader. They need context, foundations, diagrams, and examples. Write concisely for them
• Write for the skeptical marketect. Know the unique value and pitch it early
• Put yourself in the shoes of the reader: the runtime engine dev, the content pipeline dev, etc. What do they need to know to (1) understand the concepts and (2) implement?
• Just like coding, write to be read. Specs are Write-Once Read-Many. The amount of time spent writing is a small fraction of the amount of time everyone spends reading
• Introducing topics, breath vs. depth. Breath with context, followed by depth. Order most important topics to least important. Foundational topics to niche topics. Create structure for the reader's mental model early. Readers often try to bucket concepts and understand scope, components, and their interaction. Guide them in doing so. Concepts before how they are encoded in the schema/spec.
• Examples: simple to complex. Representative, not exhaustive
• Scannable with headers and diagrams only
• Build a vocabulary and use it everywhere, e.g., what can metadata attach to (tileset, vertex, texel)?
• Rigorous language. Precise writing. This is not the default in English, e.g., feature vs. instance, metadata vs. property
• Consistency
• Non-normative: advice, implementation guidelines, etc. - explicitly mark them in non-normative sections
• Context before details, e.g., why per-instance arrays before how to define fixed or variable length
• Forward references. Avoid. Organize the concepts up front then layout the sections
• When in doubt: see how the glTF and 3D Tiles spec do it
• Your extension doesn't do everything; position it in its niche, show how it fits into the ecosystem and complements other extensions

Extension Template Notes

• Why is this extension needed? How is it positioned to the current spec and ecosystem?
• Is this in the spirit of efficient transmission/runtime? What new capabilities or performance does this enable? What new algorithms can exporters, pipelines, and/or runtimes now implement?
• glTF
  • Extension spec prose
  • JSON examples
  • JSON schema
  • Diagrams
  • Any code examples or equations in an appendix (often non-normative)
  • Sample models, https://github.com/KhronosGroup/glTF-Sample-Models
  • Submit an issue to add support to the validator, https://github.com/KhronosGroup/glTF-Validator
  • Do any other key parts of the glTF ecosystem need to be updated? E.g., CesiumJS, Cesium Native, obj2gltf, gltf-pipeline, etc?
  • How and when should ratification be proposed?
• 3D Tiles
  • Extension spec prose
  • JSON examples
  • JSON schema
  • Diagrams
  • Any code examples or equations in an appendix (often non-normative)
  • Sample models
  • Submit an issue to update the reference card
  • Do any other key parts of the 3D Tiles ecosystem need to be updated? E.g., CesiumJS, Cesium Native, obj2gltf, gltf-pipeline, validator, etc?
  • Deprecation policy. Overtime should this replace something in CesiumJS, Cesium ion, etc?
  • How and when should ratification be proposed?
  • Community feedback and launch announcements

---

CC glTF Guide, KhronosGroup/glTF#1004
CC 3D Tiles Contributors Guide, which has a bit on specific consistent language