4 ms·
Yup. On CPAN, it is encouraged that the first part of your documentation after the table of contents is the synopsis[1]. The synopsis should clearly show how to
by tetha 8y ago
Yup. On CPAN, it is encouraged that the first part of your documentation after the table of contents is the synopsis[1]. The synopsis should clearly show how to do the common tricks with the library. From there you can link and refer to the more detailed documentation.
We're doing that for our internal CLI applications and it's great to be able to just copy-paste the common use case from the top of the documentation without searching much.
1: https://metacpan.org/pod/Carp https://metacpan.org/pod/Carp
- dickeytk 8y agoI feel the synopsis section of man pages often just becomes a bunch of useless garbage above the fold (for instance, look at `man git`). Using it less as a complete docopts kind of thing and more of multiple common usages (like `man tar` and what you linked) is far more useful. I think there is something here I hadn't really considered before. It's not an example, but also not a useless dump of flags. Food for thought I suppose.