[GRASS5] documentation

[Glynn Clements]

Russell Nelson wrote:

> > So, as an example, Russ's HOWTO (thank you Russ for having been
> > declared volunteer ;-))
> 
> I'd rather fix the code so it's easy to use than warn people about why
> something is going to trip them up.  

Ease of use is not the only consideration. It isn't even the most
important consideration. And ease of use for people who haven't read
any documentation is even less of a consideration.

If something is complicated for no good reason, that would justify
changing it. OTOH, some things are complicated for reasons which,
while not immediately obvious, are valid. The usual reason is
flexibility.

There's also the issue of code complexity. Anything which makes
writing new modules more complex would need to produce significant
benefits in order to be justified. It is unreasonable, IMHO, to expect
individual modules to incorporate significant "intelligence" to try to
guess the user's intentions.

OTOH, changes which only affect library functions are less problematic
(from the perspective of justifying the effort; they are more
problematic in other regards, e.g. destabilising client programs).

-- 
Glynn Clements <glynn.clements at virgin.net>