I have spent the last 16 years designing and documenting a development tool for non-programmers, and it is possible to offer the code savvy the scope they need, as well as making it all understandable to the non-coder (where easy discovery within a centralized body of information is important).
We chose to do this in two parts. The first is an overview, which reads much like a book, discussing how things work (the big picture, objects and their common properties, events, event handlers, operators, commands, and functions).
The latter is a language reference… searchable (in a number of ways), categorized, cross referenced, with an entry for every token in the language (1370+ at this point), each with multiple syntax templates and syntax examples (showing variety of usage), and a full description of the use of that token along with any possible caveats and limitations, with links to related tokens. They are all categorized by type/class, and by applicable objects (in the case of properties), as well as by concept.
While much of this info is presented on the SmartThings web site, it is all written by programmers for programmers, with insufficient example syntax, and no granular reference; leaving the java/groovy uninitiated to search online for the proper notation, which provides even less helpful results (many of which don’t even apply to SmartThings’ implementation of groovy).
Add to this the (lack of) speed, and the tediousness of the IDE and you have an environment where you would like to avoid trial and error at all cost, but unfortunately, this is the default learning curve in its present state. While all of what I have created in SmartThings works, there are pieces in many apps I see that I can only guess at their nature because they are not clearly documented anywhere.
See my post tagging you re: sendEvent.
I have asked enough questions on this site to conclude that there are a very precious few who know the answers, and this means they are simply not published, or if they are, even your devs can’t find them.
I realize that this is not trivial, but IME, it pays for itself by increasing adoption and lowering support costs. Plus I’m available! (c;