Subject: [PATCH] A Few (Small) Documentation Fixes
From: Raymond Toy
Date: Thu, 29 Nov 2012 09:22:19 -0800
>>>>> "Robert" == Robert Dodier <robert.dodier at gmail.com> writes:
Robert> 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.
Robert> Well, for the record, I think mixing exposition into examples is a
Robert> weak style. Better to lay out the facts first, then illustrate it with
Robert> examples as needed. People read computer documentation as little as
Robert> possible, so it should be organized to convey information efficiently.
Robert> Comprehending examples and inferring new facts from them, or filtering
Robert> out facts which have been mentioned elsewhere, is a needless
Robert> distraction. Why put that burden on the reader? If there are some
Robert> relevant facts, just state them plainly.
Robert> In the case under consideration (%phi), there is very little to say. I
Robert> suppose it can be argued that the documentation is so minimal that it
Robert> doesn't matter too much how it is written; that seems a weak argument for
Robert> abandoning good organization in this case, and weaker still, in general.
I read the documentation for %phi for the first time today. I find it
odd to see examples of fibtophi. I think I'd like just a note that
fibtophi exists, and let the user look up fibtophi (a hyperlink?),
which pretty much duplicates the examples and documentation here. The
represents a burden on updating documentation if it has to be updated
in two places. fibtophi should probably also include a hyperlink to
%phi.
The duplicated paragraph is odd. It would read much better
if it were shortened.
My 2 cents.
Ray