Examples are the best documentation

Say what you will about Perl, Perl docs are some of the most helpful. It's standard for docs to have a SYNOPSIS section up front that provides examples of common usage. This is followed by discussion, reference, and often more examples.

For example:

https://perldoc.perl.org/bigrat https://perldoc.perl.org/Archive::Tar

If you're writing docs for your project, consider following the Perl documentation style. Fortunately, that style is itself well documented:

https://perldoc.perl.org/perldocstyle#Description-and-synops...