Re: State of documentation of ConTeXt?

[Alan BRASLAU <alan.braslau@cea.fr>]

Ah, the great documentation project!

The problem concerning writing documentation is that it must be done by
someone who knows ConTeXt well enough to know what to say or else know
where to look or ask about subjects that are less well known to him or
her. Many attempts at "improving" the documentation have been started.

Anyone is free to write a book, but is there enough of a market to make
it commercially viable? Yet a good book can also be a key to the
success of any system.

As Hans wrote earlier, one possibility is to fund a documentation
project that would allow someone to devote the necessary time to
achieve this (as well as to allow a few key developers to take the time
necessary to assist in this project, as Mojca suggests). We would need
to identify who could fund such a project as well as who could be
qualified to carry it through.

Right now, the community (and in particular Hans) is doing a pretty
good job of providing resources "in our spare time".

Alan


On Tue, 15 Jul 2014 16:42:25 +0200
Mojca Miklavec <mojca.miklavec.lists@gmail.com> wrote:

> On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda wrote:
> >
> > I like ConTeXt (still do, I liked its approach when I first
> > encountered it). But the project is more the ongoing private
> > tinkering of a small in-crowd (that communicates with some
> > followers).
> >
> > ConTeXt is managed a bit like a small group of researchers sharing
> > a couple of complex and undocumented models/programs and tinkering
> > with them as they go along. It’s an activity without formal design,
> > but with a lot of trial-and-error/testing.
> >
> > Given that status (and the fact that it has had that status for
> > over a decennium), I don’t expect it to ever become a serious
> > product that is (semi-)professionally managed. I prefer content
> > over management every day, but something like this needs some
> > minimal management. That requires both time (=money) and
> > capabilities. Besides, the tinkering researchers may not be
> > inclined to do that, they want to tinker.
> 
> Basically all the development in ConTeXt is voluntarily. Pro bono.
> Besides "tinkering", Hans still needs to earn some money from
> somewhere. I find it amazing how much time he already spends doing
> good things for the community. But he's not omnipotent.
> 
> If there is interest from some commercial company to fund the project
> enough to allow some people to work full-time on documentation
> (including paying Hans to allow him to spend more time on the
> project), I'm sure that it could be done.
> 
> > BTW, you can’t be serious asking the users to provide the
> > documentation, can you?
> 
> There are many excellent books out there written by "writers", not the
> authors of software.
> 
> (I didn't even get a manual for Windows or OS X where the companies
> make big money. Certain things or tricks can only be done when hackers
> find a way to do X without anyone documenting feature X. And the last
> phone I bought also came without any documentation whatsoever.)
> 
> There are more than enough *users* of ConTeXt capable of coming up
> with proper documentation (depending on the definition of user of
> course, but one could count Taco and Wolfgang as users and they are
> certainly not the only ones knowing ConTeXt from inside out). But
> there's of course always a question of motivation (combined with time
> and money of course).
> 
> ConTeXt comes with full source code, so users can easily study the
> source code. 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). Ohloh estimates that it took more than 300 person-years to
> write the source code for example ;) Sure, the estimate is problematic
> because ConTeXt includes the complete Unicode as well as all
> hyphenation patterns which simply count as lines. But it's still an
> enormous project.
> 
> Oven once you remove the hyphenation patterns and char-def.lua, there
> are still 36 MB remaining. The pgf project has a 1200 page manual for
> less that 5 MB of source code. LaTeX has a gazillion of manuals and if
> you don't know what package you should be looking for, it's not really
> helping.
> 
> I agree that it would be awesome if there was complete documentation
> available + maybe three manuals/tutorials from beginner to master, but
> you cannot expect it from Hans to do all the work on his own.
> 
> Mojca

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