I haven't looked at the latest material, but there are several
problems I have seen in the past.
1. The display of 2-d expressions takes way too much space.
Since virtually no one uses "typewriter-like" displays, this looks
really dated. All the display of expressions could be done
via TeX -> GIF or XML.
Because the display is so large, there is a huge penalty for
including examples.
But this may not be feasible in a portable way.
My suggestion is to look at the Mathematica manual for
layout conventions. I don't know how much texi can do.
2. The descriptions, especially in the Macsyma reference manual,
are really not very good. In some cases I would prefer that the
manual say WHAT THIS COMMAND SHOULD DO
in addition to WHAT THIS COMMAND ACTUALLY DOES.
(which may be buggy, impossible to explain rationally, ...)
I think that the manual talking about the user in the third person is
probably bad.
Consider "if the user needs to substitute the values from solve into a
formula,
he/she(?) should try EV(formula,solve_result)".
Clumsy, in my view.
Better: "to substitute the values from solve into a formula, try EV
(....) "
but note that this is, linguistically speaking, equivalent to...
"to substitute the values from solve into a formula, YOU
SHOULD try EV ...."
and thus this is not 3rd person, but 2nd person.
Even better, in my view, is instruction of the form:
"If you wish to substitute.... , you can try ......"
This gets away from the he/she or they pronoun issue, it is more
direct, and friendlier. It
may even make it plausible to use "we" from time to time. say...
You can do (a)... (b).... or (c). We suggest that you do (a) in case .....
Anyway, that's my 1.54 Euros.
RJF
Vadim V. Zhytnikov wrote:
> Robert Dodier writes:
>
>> Hello,
>>
>> - adopt neutral tone & talk about user in 3rd person
>>
>