Re: cont-enp.pdf on lulu

[Gerben Wierda <Gerben.Wierda@rna.nl>]

On Jul 28, 2008, at 12:46 PM, Taco Hoekwater wrote:

>
> Hi,
>
> While most of what Gerben states is close enough to the truth to
> be a matter of opinion, I really object to the tone of 'there is no
> documentation'. There is, in fact, a whole lot of documentation.
> It may be incomplete (especially when it comes to recent  
> developments),
> but that is quite different from not having documentation at all.
>
> There are thousands of pages of documentation on pragma-ade.com,
> and pretending they are totally inadequate by not even asserting
> their assistance is unfair.

OK Taco, that is a fair point concerning my pov. To answer it: I have  
made my comments knowing quite well what documentation there is and my  
*personal* (your mileage may vary) experience is that it hardly helps  
me. My personal experience has been with a result of close to 100%  
that if I want to do something / find out something I am unable to  
find it in the docs. Also, depending on what doc you take, I recall  
getting different solutions (I am reminded of the various incompatible  
ways to do tables) and if I recall correctly some of it had to be  
hunted down in MAPS articles and such. Maybe the answers of my  
questions are there. But in that case the documentation is such that I  
consider myself in the situation that I am unable to get my help from  
it.

And the documentation is not just incomplete for recent developments.

I have an idea. Why not have a live ConTeXt manual.pdf where you add  
something in the proper location and compile the document every time  
you answer a question from a user? As you are the person answering  
anyway, it should be little extra work.

For instance: I have put out a question about the (afaik completely  
undocumented, incomplete and certainly not recent) endnotes feature.  
Why not take the manual now, add the info in and recompile and do that  
every time a question arrives that is not in the manual or that is  
maybe unclear in the manual? I would suggest looking at ways to make  
it as easy as possible (that is, as little work as possible) for  
yourself to keep a user&reference manual up to date. Something simple  
and fundamental as endnotes should not be undocumented. And  
limitations (like what to do if you want images in endnotes) should be  
available in documentation.

In fact, you need only maintain one single integrated document en keep  
it up to date with the current ConTeXt version. Then, when you make  
MkIV the current ConTeXt version (and not a beta using a beta of a new  
compiler) you freeze the old and move to the new.

Is it perhaps the case that  the source of the manual is so old that  
it will not compile with a current ConTeXt anymore? If not, why not  
update it so it is less than 7 or 9 years out of date? If so, what  
does that possibly tell you about how valid the contents itself still  
are?

Yours,

G

PS. To my own surprise (as I am a TeX fan) I have recently started to  
think about researching non-TeX alternatives.

PPS. Before pressing send I just had a look at what is there on the  
pragma-ade site: http://www.pragma-ade.com/document-1.htm. I do not  
see any documentation other than the 1999 excursion and the 2001 'all  
of ConTeXt' manual. Maybe I am looking in the wrong place for  
documentation?
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
archive  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________