[Rd] Section 7.1 HML documentation (PR#8484)

[Greg Kochanski]

Well, you make two very strong assumptions.

First, that your readers start in the beginning and read to the
end.
Second, that your readers are sufficiently dedicated to learn
your terminology.

The first is false:  I got to that page via Google.
The second is only true in varying degrees,
and I wouldn't depend on it too strongly.

When writing documentation, you really have to write for
the case of someone who has a specific problem and wants
to understand that problem as quickly as possible.
That means the manuals should have "local support" --
most of what you need to know should be in one place, and
everything else should be referenced or hyperlinked.

Speaking almost professionally (since I'm almost a linguist),
the word "instead" is normally used in the form "instead of X",
and you can only delete the "of X" when X is clear and obvious.

For instance, one wouldn't just write

"I go to work instead."

because your readers won't know the
alternative to work.
Likewise, with "earlier":  the underlying form is
"earlier than Y", and you can only delete "than Y" when your
readers are quite clear what you are comparing to.

That's what I meant by "dangling": that X and Y were not clear.

Hin-Tak Leung wrote:
> Greg Kochanski wrote:
> 
>> Well, I don't know how it can be precise
>> and correct when it has dangling antecedents.
>> Gramatically speaking, that's the equivalent of
>> an uninitialized pointer.
> 
> 
> I don't think there is anything "dangling" there. What the paragraph 
> assumes (and quite patently wrongly) is that the reader had encountered 
> the concept of "R connection object of the socket type" elsewhere. 
> Without that background, one tends to interprete the phrase "socket
> connection" in the traditional unix sense (i.e. = "BSD socket"), and
> hence one reads the paragraph as " XXX is older than XXX and XXX is
> newer than XXX and there had been potential problems with XXX and
> one should use XXX instead (of XXX)".

Yep.


> 
>> However, I agree with you that it probably just
>> needs a minor bit of fiddling to make sure it
>> answers "Instead of what?" and "Earlier than what?"
> 
> 
> I have re-read R-data and it seems the fault is yours. Because 
> "Connection" is mentioned in quite a major way and is the entire subject
> of chapter 6 and comes earlier than the paragraph you quoted in
> chapter 7. So it seems to be your own fault of trying to
> understand chapter 7 without noticing the header of chapter 6
> nor reading it!

That may be so, but it is irrelevant.   The object of this
exercise is not to assign blame, but to make the software
more useful for the next user.

Consequently, you might want to fix it (even if it is my fault),
so long as it is likely to help the next guy (even if it is his fault).
And, I contend that a lot more people Google into the middle
of the documentation than read it from beginning to end.  QED.