Re: [bug #38433] Example for "eval" in documentation contains error with "define"

[Reinier Post]

On Wed Feb 27 17:02:03 2013, address@hidden (Philip Guenther) wrote:

> IMO, the suggestion that was proposed would reduce the overall
> usability of the manual and increase the confusion.  I seen it tried
> in multiple ways** in other open source projects (and at my day job)
> and the results were never complete (there were nuances left out),
> took a large amount of effort, and always made a small set of people
> happy and a much larger set of people unhappy.

Can you list one or two examples?
Doesn't the amount of pain depend on how it's done?
E.g. I can imagine that keeping a set of crosslinking footnotes
of the form 'this has changed in version x, see the corresponding place
in the x-1 docs' is a lot easier than trying to document several versions
within the same document.

[...]

> (Did the manual to your car or bike or computer include comments
> throughout it describing how this year's model is different from the
> previous years?)

The problem is that people find documentation elsewhere and need to be
aware which version of the bike or model it applies to.  You can argue
the issue rightfully belongs on someone else's plate, but the fact
is that lots of make users appear to lose a lot of time over this,
especially between 3.81 and 3.82 (I have been bitten by it as well).
The prime purpose of documentation is to keep users from wasting time
on figuring out things that can be looked up instead.

-- 
Reinier