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 ___________________________________________________________________________________
