Subject: [PATCH] A Few (Small) Documentation Fixes
From: Robert Dodier
Date: Thu, 29 Nov 2012 07:22:14 +0000 (UTC)
On 2012-11-28, Kris Katterjohn <katterjohn at gmail.com> wrote:
> It just looks rather funny to me having verbatim copies so close to one
> another when the examples just illustrate precisely what the text is referring
> to. I was simply thinking of descriptions which interlace text and examples
> (e.g., to_poly). Thinking about it again now, perhaps my patch should have
> (essentially) just removed the text "Examples:" as well.
Well, for the record, I think mixing exposition into examples is a
weak style. Better to lay out the facts first, then illustrate it with
examples as needed. People read computer documentation as little as
possible, so it should be organized to convey information efficiently.
Comprehending examples and inferring new facts from them, or filtering
out facts which have been mentioned elsewhere, is a needless
distraction. Why put that burden on the reader? If there are some
relevant facts, just state them plainly.
In the case under consideration (%phi), there is very little to say. I
suppose it can be argued that the documentation is so minimal that it
doesn't matter too much how it is written; that seems a weak argument for
abandoning good organization in this case, and weaker still, in general.
best,
Robert Dodier