I learned Perl as a first programming language, and to this day I maintain that their documentation is better than that of any other language I've tried. Putting a synopsis with example syntax at the very beginning is, IMO, the ideal.
Example at [1]. I can take this and run with it, after reading for less than 15 seconds I know enough to start working.
Example at [1]. I can take this and run with it, after reading for less than 15 seconds I know enough to start working.
[1] https://metacpan.org/release/TIMB/DBI-1.616/view/DBI.pm