Use LLMs to improve clarity and accessibility for 3.2.1?

[handrews]

One thing worth considering is whether to do a 3.2.1 that is basically the result of us asking an LLM to rewrite the 3.2.0 spec for conciseness, clarity, and accessibility. I've long said that the spec would be much improved if we had a thorough review by a professional editor and tech writer. In the absence of finding that in a volunteer capacity, it might be worth seeing how LLMs could improve the prose.

I am especially thinking of the more complex areas I've added over the last few patch and minor releases, particularly some of the appendices. They're so complicated that I sometimes have trouble figuring out what they mean and I researched and wrote them.

I don't want to speak for anyone else, but this is not an area where I feel the need to preserve my own writing voice. I'm reluctant to use AI to write GitHub comments (and would say so if I did), but when it comes to the public specification text, I'm strongly in favor of producing the most useful text for OAS users.

We would, of course, be open (in the introduction) about the LLM involvement. But I think as long as we are clear about what we did and why we did it, people will understand that the usability of the OAS is what's important. This isn't like writing a novel where there's some assumption that you're primarily reading an author's personal creative vision. We just want this thing to work for people.

[ralfhandl]

I wouldn't change the document structure in a patch release. A patch release should just apply minimal patches to fix broken things.

A minor release would be a better candidate for a document restructuring. And I'd then actually have a "refactoring" minor release that just restructures the spec without adding or removing features.

[handrews]

@ralfhandl I didn't intend to restructure the whole thing. I was more thinking improving the wording within the existing structure.

Although do recall that 3.0.4 and 3.1.1 were pretty maximalist as far as "patch" releases go, and AFAIK we did not get any complaints. But this is about text, not structure.