On Sat, 26 Jul 2008 04:38:42 +0200, Gerben Wierda wrote:
My expectation is that the situation with respect to user documentation is not going to improve soon.
I don't know one way or the other about this. I do know that there are only a few people (fewer than ten) who can even think of fixing it. I can write clearly, but if I were to try to write documentation for ConTeXt, I would have to waste all my time asking stupid questions of that same tiny group of people. 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. - It's already proven that development isn't going to finish, but evolve. - No one else can document ConTeXt without bothering the same people every five minutes anyway, so what's the difference? - 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. Perhaps a reasonable compromise would be to publicly set a date in the near future (sometime before the end of 2008) as "code-freeze day", when development comes to a complete stop and the documentation project begins. Bringing a writer from outside and getting him "up to speed" has obviously become completely impractical. Sincerely David