Readability of the spec - food for tought

[martencassel]

In terms of technical writing the spec in its current form is very hard to read.
I believe the text has some very basic technical writing quality issues.
Im must say im not a technical writer professional.

Most of the basic technical writing ideas in say https://developers.google.com/tech-writing/one could solve these issues.

If you are a naive registry implementor like me, one challenge is skimming the text, and scanning it quickly. Finding logical organization of say protocol requests / responses, header rules etc and notes.

But its also part of the specs charm.

The spec is a perfect, exercise in applying these ideas, i did a rewrite here (withouth llm) https://github.com/martencassel/distribution-spec

A simple solution is to break up the very long paragraphs into logical chunks that flow with the content, and present them in a more skimmable way.

[sudo-bmitch]

Hi @martencassel. There's wide agreement the spec needs reformatting. Though I think we'd go a bit of a different direction than what you've proposed. See #566 for some of my own thoughts.

At present, I can think of several blockers preventing this:

1. Other priorities are taking our focus. A big one is the need to support different digest algorithms. And there is a major refactoring of the conformance tests that were included in that effort. See Conformance test redesign #588.
2. Maintainers have a limited availability. Most of us are doing this as a side project. So finding the time for one of us to make the rewrite probably won't happen soon.
3. The work for this would be a stop-the-world effort, breaking old PRs and holding up new PRs until it was merged, or causing a lot of rebasing of PRs that causes delays.
4. The project barely has enough active maintainers to merge changes today. This is why even simple changes tend to take several weeks to approve, that's just how long until we can get a second review. For larger changes like the conformance test rewrite, I'm expecting that to take months at best. I'd expect a rewrite of the spec itself to take even longer to get the approvals.

[martencassel]

Thanks for the quick reply. I now better understand the situation we are in here.