Right, to show I'm not just empty words, I've just spent ~90 minutes preparing the beginnings of some decent documentation.  Presenting http://github.com/eegg/ConTeXt-doc : basically, I've:

(1) wget'ed all the English HTML from the texshow documentation
(2) converted it all to reStructuredText using html2rest.py (http://bitbucket.org/djerdo/musette/src/tip/musette/html/html2rest.py)
(3) plugged the result into a fresh installation of the Sphinx documentation system
(4) Pushed the whole thing to a new github repo (including generated HTML so you can take a look without bothering to install Sphinx)

To note:

- Sphinx really is state-of-the-art.  I suggest you spend a few minutes browsing http://docs.python.org/ to see what I think is 'good documentation.'  It runs on reStructuredText, a powerful, purely semantic and readable (almost invisible) markup.
- Revision control, people!  I strongly encourage everyone to fork and push this repository.
- There's a hella lot of documentation to do here.  Most of the pages in texshow are just placeholders.  There's also massive capabilities in something like Sphinx to organize the code documentation with sensible commentaries.
- In my humble opinion, TeXies need to get out of the habit of 'self-documenting' TeX using TeX itself.  TeX is not some replacement for all markup, it's for producing beautiful books (OK, and some presentations); in any case, this habit smacks of introversion.


To address previous points in this thread:

- Maybe I exaggerated a tad on how little documentation there is.
- Why on earth is there a git repository that is just slave storage?  That uses about 1% of its capabilities; it seems a terrible waste.


So, thoughts?


James

On Thu, Mar 4, 2010 at 12:08 AM, Aditya Mahajan <adityam@umich.edu> wrote:
On Wed, 3 Mar 2010, James Fisher wrote:

Also, re "there is only one  ConTeXt developer --- Hans Hagen":
I'd suggest a few reasons for this are:
(1) in order to develop on a project, you first need a the high-level
appreciation of the system that comes from documentation

MkII is fairly well documented. See
http://wiki.contextgarden.net/Official_ConTeXt_Documentation

MkIV is only documented at http://www.pragma-ade.com/general/manuals/mk.pdf. Part of the reason is that it is still changing.

The documentation is not perfect, but is huge (more than 1000 pages last time I checked). Saying that ConTeXt is undocumented in not fair, IMO.


(2) ConTeXt does not have any revision control system that I can see (the
only source code browser seem to be http://source.contextgarden.net/ which
looks entirely custom); all I can find is the SVN of the in-progress manual

git clone http://dl.contextgarden.net/distribution/git/

Hans does not use a public version control system. The above repository is a daily snapshot of ConTeXt files.


(3) The low-level macro documentation at
http://texshow.contextgarden.net/is a start, but: (i) instead of a
custom system with basic editing, a modern
documentation system (I'm thinking of http://sphinx.pocoo.org/ used for the
*fantastic* documentation of the Python library) would be more productive,
and (ii) this documentation is completely non-structured, being just an
alphabetical list.

(This from the community that came up with "literate programming"?)

The sources are fairly well documented. Just read the source files, or see http://foundry.supelec.fr/gf/project/modules/ for PDF output.

The question of documentation has come up many times in the past. Everytime we conclude that we need a volunteer to do maintain the documentation, but so far no one has stepped forward (hint, hint).

Aditya

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