Hi Konrad,

>>> Well thats two improvements to the documentation.
>> Perhaps a perfect candidate for the Wiki?

> Hmm.
> var - Variable: Either a symbol or a cell
> (set 'var 'any ..) -> any
>     Stores new values any in the var arguments. See also setq, val and def.
> Even taken in concert these two snippets don't actually explain what
> will happen if var is a cell. It may be obvious (if you already know)
> that if var is a cell than action will be taken on the car part.
> However it does not actually say so. I note that the definition of con
> does say so even though its signature has the more specific data type
> of Lst.
> The best a very careful first time reader could pick up is that the
> behavior is not explicitly spelled out. They could then, guess,
> experiment or ask.
> I would say that there are some functions where additional verbosity
> is warranted. the function for assigning values is one such place.
> Especially when the acutal behaviour may not be what people with Lisp
> experience expect.
> While succinctness is good in documentation, it is possible to have
> too much of a good thing.

nothing is perfect but rather than arguing with Alex about quality of
his documentation, would not it be easier and more useful to take
action and put it in the picoWiki?  I think everybody would appreciate
your knowledge and it would be preserved for newcomers too.  It would
at least make it easier for Alex not to spend his lifetime maintaining
his documentation to everybody's tastes and focus on his clients,
writing code and having fun instead;-)

There are many different Lisp dialects so people's expectations could
vary depending on their background.  A wiki page for people comming
from Common Lisp background, for example, would be great!



Reply via email to