About the documentation, I also think there is much to improve. When I started learning Freepascal/Lazarus I followed the "Getting started", which is quite short and for learning the Syntax I used Delphi-tutorials and references. For the language itself this was ok, but the struggle with LCL was huge. I nearly gave up several times. At that time I didn't know about the code examples. The LCL-doku was to cryptic for me as beginner. Delphi-doku sometimes helped, but there was a lot of trial and error. And somehow wasted time. Especially as I didn't understand how LCL is connected to the operating system, how the application actually works (message queue etc.).
While I say that, I'm aware that I should contribute such things as well and I understand why it is the way it is.
Another aspect, why Freepascal is not as popular as it should be, in my opinion is the syntax with its begin-end orgies. The modula syntax "if .. then .. end" is much nicer. In the beginning I thought: "From which century is this language - Middle Ages?". Today I don't care anymore, the additional writing effort is not significant. But I'm sure its a successful method to discourage interested people in choosing Freepascal. It just gives the overall (false) impression of an outdated language/environment. Loops and ifs occur every several lines so this "issue" is all along the source code.