Subject: Seeking areas of little or weak documentation
From: Richard Fateman
Date: Sun, 20 Mar 2011 17:46:14 -0700
On 3/20/2011 5:20 PM, Henry Baker wrote:
> As a new/old occasional user, I would say that the standard manual leaves a lot to be desired.
I agree entirely.
There are examples (like the Mathematica manual) to use as a guide,
though people complain about that too.
Maybe the Maxima by Example stuff could be used as a model, also.
There are also a few pieces of manual that could use English
copy-editing, like the translated-from-German
plotting stuff. {It is entirely understandable, but not in conventional
idiomatic English}
I also have periodically suggested that an alphabetized listing of error
messages and what they mean
would be a service.
On the other hand, the idea that someone who doesn't know much about a
program can write documentation
for that program tends to leave me cold.
In my experience, copy-editing by an experienced professional makes some
tech stuff much much better to read. Unfortunately it tends to occasionally
change the meaning, sometimes by 180 degrees,
and so must be examined carefully.