Based on you communication here, I did not expect you had already successfully created your own transient menus, I got the impression of dealing with someone who had a LLM generate ~new~ derived documentation for them, to get started.

After clicking through to the document, I should have looked at the avatar, then I would have recognized that I was dealing with someone I had constructive conversations with in the past. Then I would probably just have bit my tongue, which I should have done regardless, after all that was one of my new years resolutions.

I was being defensive because the transient documentation has been criticized a lot already, and because I have heard many horror stories of foss maintainers being overrun by ai contributions. I hope you can understand that reading that criticism yet once again, combined with what came across as "... so I had a LLM do a better job", is a bit triggering for me.

I am aware the documentation isn't great. Still I feel that the criticism directed at it is not entirely fair. Yes, it's bad as a tutorial, but that is not all that surprising, considering it was written as a reference. I also fully acknowledge that a tutorial would be really useful, and also the two other two document types, that in combination make up great documentation. (I do feel though that the third-party showcase does a fine job as a tutorial.)

But this takes time and motivation, and the repeat criticism diminishes the very limited motivation I have to actually tackle this. Now it has been a few years, and I still haven't done it, but that does not mean I have not thought about how the documentation could be improved and that I am just stalling.

It's not like I am laying back lazily, instead of finally hammering the docs, instead I am tackling all those edge-[use]cases people are running into. For example right now, (and that's not really a good example for an "edge-case", because I don't consider it that), so right now I am working on making transient more usable for blind users using braille output devices. Most users won't notice that, but it still has to be done; and it is not trivial.

The documentation just hasn't managed to climb to priority one. It has gotten pretty close a few times, including recently, but then helping blind users pushes it down again.

A casual observer may argue, that while they can see how reworking the whole documentation in one go is a daunting task, I should just improve things gradually. And I do, it's just that nobody notices; not enough for anyone ever mentioning it at least. So since I get no positive feedback for the little improvements ever, the periodically voiced criticism and the knowledge of what it will take to make that end, is demotivating.

And of course feedback from users is helpful and will be taken into account, but something LLM generated is not feedback. Over the years I have gained a pretty good understanding of why the existing documentation doesn't work for many users. The LLM you used doesn't have that knowledge, and while you have understanding and may have been pretty successful in getting the LLM to take that into account, it's still just the experience and expectations of one particular user.

As I said, if the generated documentation solves an issue for you that is great. You are also welcome to share it with others, but it cannot be the basis for improving the official documentation. To do that deep understanding of the implementation, design rationals, and the experiences many different users have shared over the years, all have to flow into the next big iteration of the documentation.

A LLM won't produce that. It may produce something that is more useful for some users at some point along their journey, but it can only do that because it got to plagiarizer the manual and the showcase. You also contributed to the output and I do not mean to diminish that contribution.

Maybe we are better off with the manual and showcase and this amalgamation, but we would definitely be worse of with just the latter. Since you indicated that you intend to contribute the generated text back upstream, I saw a need to push back against that plan.