←back to thread

Examples are the best documentation

(rakhim.exotext.com)
409 points Bogdanp | 1 comments | 09 Oct 25 19:34 UTC | HN request time: 0.202s | source
Show context
tmoertel ◴[10 Oct 25 11:21 UTC] No.45537603[source]▶
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...

replies(2): >>45538356 #>>45542595 #
1. adrianmonk ◴[10 Oct 25 19:08 UTC] No.45542595[source]▶
The examples in the Perl documentation are very well chosen, too. They aren't just a quick way to get up to speed. They aren't just code that you could use as a starting point and modify for your purposes.

Instead, many of them are almost like exercises to help you work through the ideas that the documentation is presenting. Some of them help you see how a syntax or other language rule applies. Sometimes the documentation presents two pieces of example code and walks you through why they're equivalent, helping you understand the language better. Or why they're almost equivalent and what the differences are.

In a lot of documentation, examples give you a superficial understanding but are a dead end if you want to go beyond superficial. In the Perl documentation, examples are often a bridge to a deeper understanding.