Re: State of documentation of ConTeXt?

[Mojca Miklavec <mojca.miklavec.lists@gmail.com>]

On Sun, Jul 20, 2014 at 2:14 PM, Gerben Wierda wrote:
>
> Sorry, you can’t expect users to be able to do that. Lamport
> created LaTeX *and* wrote the “LaTeX User’s Guide and Reference manual”.

<teasing>
Indeed. Sorry, you can't do that to users. Christian Schenk also
created MikTeX (I still have MikTeX files from 23 years ago) *and* is
still developing it actively and answering emails from users.
</teasing>

> The authors mentioned below were all developers too. You need that level of
> understanding to write a manual.

What kind of developers? Did they contribute to the LaTeX core? (Many
ConTeXt users are developers, but it highly depends what you count as
a developer.)

>> The project could easily employ two people to work full
>> time just to keep up with the pace of development (once they would
>> catch up).
>
> I would expect it to be far less than that once you have the documentation.

(a) You probably never tried to follow how fast ConTeXt is being developed.
(b) There's a tricky "once" in the sentence.

Ad (a): I've heard a rumour (that might just as well be false
information) that authors of the LaTeX companion or maybe LaTeX
Graphics companion had a serious problem. They hardly managed writing
as fast as the packages described in the book kept developing.

Also, if I see correctly, the book "Guide to LaTeX" has been published
in 2003. Even for LaTeX that's "a totally outdated book" and doesn't
even scratch the surface of LuaTeX, XeTeX and OpenType fonts - the
most useful things that most users should switch to nowadays. The
LaTeX Companion is probably even more outdated and "useless" as it
doesn't even scratch the surface of many useful packages that surfaced
since the last release. I have the LaTeX Graphics Companion on my
bookshelf for example, but even if I was still using LaTeX, the book
would be almost useless to me nowadays. Almost none of the things I
would want to use are covered there (starting with TikZ for example).

The beginner's tutorial for ConTeXt is no more outdated than these
books are (but of course these books were more complete at the time of
writing and probably went under many more proofreading than the
ConTeXt tutorial, with "professional writers" involved).

I'm exaggerating a bit on purpose. But not much.

> Hans & Taco: how much money would need to be raised to produce something of
> the quality of Kopka & Daly’s “Guide to LaTeX”?  or Goossens, Mittelbach &
> Samarin’s “The LaTeX Companion”?

What do you mean with "of the quality of these books"? Having a
similar number of pages written in comparable quality (something like
a revised beginner's manual) or so complete in description of the
functionality as the mentioned manuals?

My estimate would be that a complete context reference with
well-described options and including trivial examples would require
cca. 10.000-50.000 pages. Maybe others have different estimates, but
now do the math. (Existing manuals like MetaFun or the old cont-en.pdf
are roughly 400 pages. But that's nowhere near 10 % of the ConTeXt
functionality. One would need to document the whole TeX part, the
whole metapost part, the whole lua part, the whole xml, all perl, ruby
and lua scripts, write better man pages, probably list the whole
Unicode to show the ConTeXt names in one appendix ...)

> Because, I don’t think this will happen
> unless some money is raised to pay for it.

> I would gladly donate in a crowdfunding initiative for a good book. But how
> much is needed to make it happen?

I would gladly donate as well. But probably not anywhere near the
amount that would suffice even if a nontrivial number of users
contributed the same.

Mojca

PS: the example you linked to asks for 30 EUR for a 220 page book. If
the same calculation is applied to my estimate of the number of
required pages, 22.000 pages would translate to 3000 EUR per copy.
___________________________________________________________________________________
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  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________