Updated glTF 2.0.0 Specification Now Canonical

[khronos]

Khronos has released a new version of the glTF specification in preparation for submitting glTF 2.0 as an International Standard

The new glTF 2.0.0 specification does not introduce technical changes that will directly impact existing tools and engines, but it aligns glTF with the rigorous drafting criteria needed to be accepted as an International Standard. The new specification incorporates technical clarifications, bug fixes, and is now authored in the AsciiDoctor markup language with the source available under CC-BY 4.0 on GitHub for easier community feedback, contributions, and downstream remixing.

Read about glTF’s ongoing journey to become an international standard and the updates to the new glTF 2.0.0 specification.

[technik]

After trying to get used to the new documentation, I have to say this feels like a terrible downgrade.
The old documentation, embedded in Github’s readme.md was a lot nicer to read and also a lot easier to contribute to.
In terms of being nicer to read, the old markup had nice margins, more consistent fonts and colors, and generally adapted very well to all monitor aspect ratios. Also, not having the index on the side taking screen space all the time made it a lot more friendly to vertical displays.
In terms of being easier to contribute to, the entry barrier of editing markup is very low, meaning users with all kinds of background could easily contribute.
Instead, now a user needs to figure out that now source and doc are not the same thing, learn asciidoc, and build the whole thing just to see or make a change. While in the past, you could even compare different versions of the doc by simply looking at the commit history.
This is a loss in both functionality and readability. And if one of the goals was to make it easier to contribute (as it is stated in the linked post), that goal as clearly been missed.
I understand both that this unifies the doc style with other Khronos group standards, as Vulkan’s, and that the new pipeline makes it easier to generate coherent html and pdf versions. But documentations, like code, are read many more times than they are written, and so readability and accessibility should be above maintainer convenience.
I honestly provide this feedback with the best of intentions, with the hope that we can restore what was a better user experience.

[Alfonse_Reinheart]

If I were to break down your criticism into the points you’re trying to make, I’d summarize it as follows:

• You find Github’s Markdown renderer to be more readable than Asciidoctor’s HTML.

• You find it harder to contribute because of… well, it’s not really clear. I’ll come back to that.

---

On Readability

Personally, I find Github’s renderer to be… adequate. If you just need to drop some text on people, it’s fine. But it’s nothing to write home about.

Font selection? I mean sure, I’m personally not a big fan of serif fonts on a screen. And the one they choose is very, vertical. which is weird. But it’s still better than Github’s “font selection” that seems to consist of “whatever your browser uses”.

You may not like the TOC on the side, but it make it so much easier to actually find things. To be in one part of the document, and need to jump somewhere without having to reach for a keyboard to go all the way back to the top. Yes, I wish there were a way to have a toggle button to be able to turn it on/off as needed.

Then there’s a matter of readability you neglect: printing. Github’s renderer has no print functionality; it’s just whatever your browser spits out. That may be adequate to some degree, but it’s hardly professional. And yes, being able to print stuff out and read it offline still matters.

Overall, I don’t find the readability of the document to have been compromised. Yes, individual people will have personal preferences, but I don’t see anything significantly outside of personal feelings with your argument here.

---

On contributions

This is an argument I don’t understand at all. You claim that “a user needs to figure out that now source and doc are not the same thing”. But that was always the case. It’s not like you’re looking at the raw Markdown when you’re looking at the glTF specification. It’s a rendering of it.

The only difference is, I guess, that you can’t preview it in Github. Well… so what? There are dozens of preview tools out there for Asciidoctor. There’s a perfectly adequate plugin for Visual Studio Code that can handle it just fine. You need not “build the whole thing just to see or make a change”.

Also, “learn asciidoc” is not exactly a Herculean task. Asciidoctor is pretty readable markup. It’s different from Markdown, but Markdown is different from other text markup languages. You can look at an Asciidoctor file and have a pretty good idea what’s going on. If you need to make a few wording corrections or whatever, it should be no problem to just edit the files and fix the words.

And I have no idea what you’re referring to with “while in the past, you could even compare different versions of the doc by simply looking at the commit history.” You can still do that now. Asciidoctor isn’t binary; it’s perfectly readable and entirely diff-able text. No different from Markdown.

Overall, I feel like you should provide clearer examples of the problems if they are going to be corrected.

[donmccurdy]

There were technical reasons that the specification could no longer be managed in GitHub Markdown, and (while it may not be obvious externally) from the perspective of those contributing to the specification on a regular basis the switch to AsciiDoc had become necessary. I think it would be best to look for solutions compatible with AsciiDoc.

---

About legibility and ease of contributing, I do agree that more work should be done to “catch up” to what GitHub’s Markdown preview/editing provided out of the box. Professional studies and best practices in typography are a real thing — these aren’t just subjective preferences — and particularly the line lengths really should be capped in long-form text. But there’s no technical obstacle to doing this in AsciiDoc vs. Markdown.

I think there may also be ways to lower the barrier to new contributors, such as the “[ edit ]” links appearing next to headers in Wikipedia. This is a bit more of an open-ended suggestion but could be worth discussing on GitHub. With some care, I think that the web documentation can very likely become more reader-friendly than the previous Markdown solution was, in addition to solving the Markdown maintenance issues.

[donmccurdy]

Related changes (not yet deployed to the site, I think) – https://github.com/KhronosGroup/glTF/pull/2041

[technik]

Hi, thanks for addressing the feedback. Let me clarify my points on contributions.

• What I meant by “source and doc are not the same thing” is that the source used to be the same file that you render. Moving to a separate source file plus a compilation step is more cumbersome and less convenient. The best proof of this is that the repo now has about 40 lines worth of instructions on how to contribute, while before it didn’t need any instructions. Now you need to learn about github actions and docker? I don’t think that’s a justifiable entry barrier to contribute to some docs. You can make the argument that asciidoc can also be previewed in github, but: A) it’s not the default thing github renders, so you need to know what you’re looking for in order to find it, and B) As has been said already, the render is worse and more incomplete than the old markdown was. So now it’s a matter of choosing which downgraded experience you prefer.
• Being able to preview your changes directly on github, browsing your fork of the repo in your web browser, without needing an extra tool is definitely a plus (you could even fork and edit it in place in github without cloning it locally). Sure, maybe there are tons of tools out there, but before you didn’t need a tool, and now you do. So if working in asciidoc is not something you normally do, that’s an added barrier.
• Learning asciidoc may not be a huge task, but again, is an extra burden compared to the previous state of affairs. Markdown is pretty ubiquitous. Being used in pretty much every wiki since wikipedia. Don’t know what the benefits of asciidoc are compared to markdown, but the point is that less people know it, so again, it’s less accessible than it used to be.

I understand the reasoning for going to a new tool if frequent maintainers felt markdown wasn’t enough. But I expect that as an open source project the focus should really be in making contributing accessible to as many people as possible. And this step in making it more convenient for specialized developers at the cost of a higher entry barrier for the broader audience goes against that direction.