>I mean docs that assume I've never looked at any other GUI system and don't know what an event even is, much less how to register one.

Got it now. From your initial comment in the thread (you used words like 'Threw a few gui components onto the blank form and hit compile.', I thought that you were a programmer with knowledge of at least the basic concepts and some practical experience of GUI development in at least some other GUI dev env. And my answer was based on that assumption. I now see that, whether you are an experienced programmer or not, you are looking for docs that start from the beginner level and are very comprehensive.

I have to say I sympathize with that viewpoint. It would be great if all software products were documented as well as that. However, going by real-life experience, I am not sure that many are.

>What if I'm a first-time programmer or have only ever programmed in MIT Scratch? What if I'm a PHP programmer? Do the Lazarus components work like Swing? Do you register event handling the same way?

Got it. But see my answer to your next point below.

>I want tons of examples for every component--examples that start simple and work up in terms of complexity with comprehensive explanation along the way and I want it all linked under "Documentation" off the front page.
Now that's a lot. I recognize that. But I don't care. There are whole books available for Swing, JavaFX, Windows Forms, and WPF, not to mention Web Design. That's the standard today. Book scale documentation...

Yes, there are books - and there were, years ago too, for earlier products of those times. (In fact, see my other comment in this thread, in reply to teraflop's comment about door-stoppers - https://news.ycombinator.com/item?id=12045536 :) Again, though, going by my own experience, there are not many software products that have that level of documentation in the product or online help. (Microsoft MSDN and Borland earlier come to mind as some that did.) I am not saying this is a good thing. As you say, I've also found, that one often has to resort to books on the subject of that software (if they are available - since they are not available for some less popular subjects). I've learned many different software technologies that way - via in-depth books on the subject, that I bought, or borrowed from company libraries.

>I'll say it again: I'd like to use Lazarus. I spent the morning programming a desktop application that could have been done in Lazarus, but it wasn't because I'd rather build programs than decipher an undocumented system, and I suspect I'm not alone.

Out of interest, what technology did you program it in?

No, you're definitely not alone.

However, in the kind of doc scenario that you describe (e.g. for Lazarus), there are still ways, though somewhat less efficient, of getting the learning and work done. Like this: read what docs are available (thoroughly, over time), read the sample programs, run them (correlating the code with the docs available for the code in the sample), step through them in a debugger to see what happens to program state (i.e. variables) internally as the program runs, read a lot of posts on the mailing list for the software, ask relevant questions on the mailing list as needed, to help you learn, share your own learnings on the same list, google for other online info on the topic, such as blogs, free online tutorials, etc. etc. A lot of people, me included, have learned those techniques over time and use them to overcome somewhat the disadvantages of less than perfect documentation. I realize that you may know all this already, but thought of posting it for the benefit of some readers who might not. As a trainer, I often find that beginners are not aware of many of these learning techniques - which are pretty effective, over some time. The main thing many of them know is how to use Google and StackOverflow, and if they don't find the answer there (and quickly), some of them give up overly soon (and thereby not meet their goal).

HTH.

Edit: grammar and typos.