Multiple readings of the manual, and also the Customization Types 
section of the Emacs Lisp manual, are a requirement. The library isn't 
easy to use, which is not it's fault. It hides incredible power. 
However, the library's manual could use improvement.

I searched and read the Customize mailing list. It has more spam than it 
does messages from Custom.el or Widget.el users.

Would anyone like to collaborate to improve /The Emacs Widget Library/ 
manual? Are there any active Emacs Lisp hackers that actually understand 
this library at a deep level? Every non-trivial example I've seen in 
other source code is poorly commented, which I think is a reflection of 
frustrated hackers simply wanting to get away from that library because 
they've finally managed to get it to work and don't want to think about 
it anymore.

I'm writing a package using the library, and I'm still quite lost while 
reading the manual. It's been days that I've spent with the manual, so 
it is not one or two quick readings. I have studied it, yet I am 
bewildered at times.

One aspect that is confusing is widget definition with widget-specific 
argument handling. Built-in widgets handle arguments after the 
keyword-value pairs in widget-specific ways. How do end users create 
such behaviour in their own widgets? The answer is a function value for 
the widget-create keyword, but this is a difficult thing to implement.

---

TL;DR:

The Emacs Widget Library manual could use a re-write, preferably 
following the Diataxis documentation framework if possible. Does anyone 
want to collaborate over the long-term, creating a study group and 
editing the manual to a high standard to benefit the community and 
ourselves?

Regards,

An ape riding a gnu.