Re: cont-enp.pdf on lulu

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

On Jul 27, 2008, at 9:40 PM, David wrote:

>> From my own selfish point of view, the solution is simple. A freeze  
>> on
>> all code, not even allowing bug fixes, until there's a comprehensive
>> and unified document written by Hans and Taco (plus whoever else)  
>> that
>> explains how to use all the features of ConTeXt, covering absolutely
>> all possibilities including any features that are currently
>> half-finished. Unless a new bug is introduced tomorrow that makes all
>> ConTeXt projects come out completely blank, the nonexistent
>> documentation makes all other bugs insignificant. (In fact, many
>> apparent bugs turn out to have secret workarounds anyway, and those
>> would obviously be in the documentation.)
>>>
>>
>
> I know that such a project is viewed by Hans and Taco & co. as a waste
> of their time, and as something that should be done only after the
> current burst of development is finished.

I think this assessment is correct. And this is IMO also the problem.  
It is a waste for Taco & Hans because they themselves do not need  
documentation. Others do. Hence my analysis that ConTeXt is not a  
product but a personal swiss army knife for those few that actually  
work on ConTeXt and for all other users it is a borrowed swiss army  
knife without a proper manual.

> - It's already proven that development isn't going to finish, but  
> evolve.

Hence my analysis that there will probably never be decent  
documentation unless attitudes change. And as long as Taco & Hans keep  
developing ConTeXt it will probably not be documented. And gauging  
Hans & Taco, they will keep on developing ConTeXt until they stop  
ConTeXt alltogether.

> - No one else can document ConTeXt without bothering the same people
> every five minutes anyway, so what's the difference?

I was attracted to ConTeXt partly because at first sight the interface  
looked promisingly clean and orthogonal. But the fact that only Hans &  
Taco can document ConTeXt for users and that all kind of secret  
workarounds are needed to make it work seems to indicate that  
assessment was wrong.

> - Documentation *could* be maintained and updated by someone outside  
> of
> the small group, *IF* there was a reasonably up-to-date base of  
> correct
> and complete documentation for them to start from. Currently, there is
> no such thing.

Even that would not work because such a documentation maintainer would  
not be able to keep up with finding out what changed.

You know what is funny and telling? Hans & co quite recently produced  
a detailed, well written 158(!)-page document about the change from  
ConTeXt MkII to MkIV. This is documentation (promised to be kept up to  
date) about the technical process of developing ConTeXt/LUATeX. About  
how it works, about technical issues regarding speed etc. Most of it  
will be for ever hidden from and not interesting for ConTeXt users.  
158 pages. That is book sized! For intermediary documentation of an  
ongoing technical development process.

See: http://www.pragma-ade.com/general/manuals/mk.pdf

There is no reason for a project to be frozen to create documentation.  
What is needed is that the developers accept that user documentation  
is as important as technical documentation and technical work. The  
developers currently see user documentation as a waste of time,  
because they do not need it themselves, they 'should do that when the  
development is finished'. What it actually means is that they like  
technical work far more than documentation work. So, technical work  
will for ever get a higher priority above user documentation work. And  
there will always be technical work that needs to be done before the  
nasty task of creating proper documentation is taken up. Concurrently,  
the technical work itself is indeed in many places unfinished, half,  
etc., mainly those places that the developers themselves are not  
interested in as users or where they know about workarounds and hacks.  
Writing user documentation in fact forces the developers to end that  
state of affairs and forces them not only to do documentation work  
(which they do not like) but it also forces them to do technical work  
in areas they do not like nor find interesting for their own uses.  
Hence, again, the assessment that ConTeXt is a personal swiss army  
tool for a few people.

I am really wondering these days. Is there a serious stable and usable  
(and supported) alternative for TeX for large projects, with many  
cross references, footnotes, endnotes, etc. etc.?

G
___________________________________________________________________________________
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
___________________________________________________________________________________