Unix man pages were/are driven by a standard set of macros. Why not agree
on such a standard. All software should have a “ruby page” at minimum.
Other documentation is welcome. But the rp should be written to the level
that it is complete.
Info is a second attempt at a documentation standard. But I still favor the
man page. It is like good coding as simple as possible but not simpler.
Nowadays we have the added possibility of hypertext for real-time
cross-referencing.
John