Re: Ideas for improving documentation of ConTeXt

[Hans Hagen <pragma@wxs.nl>]

On 10/10/2016 7:04 PM, Jean-Pierre Delange wrote:
> Dear List,
>
> This discussion (and proposals) is very interesting and I am afraid to say that all the points of view are relevant. But the core idea of Jonas is to get a kind of samples database where access is defined by key-word as "columnset" or "frame", etc. I don't know if making this kind of tool is as simple as it appears to be, but why not ? Surely, the individual (or group) has to be very devoted. Certainly it is possible to get code containing many errors, but Jonas would be inspired to get a further enquiry on this matter. Surely, there is a need to access quickly to the relevant information, but I don't know if it is possible to clear the way much more than the ConTeXt Garden wiki allows to do so.
>
> I order to learn ConTeXt for my own purpose and work, I have begun to start a Wikibook, because a few months ago I simply didn't know the name of ConTeXt, but I was sure that it was a best way for me to use it than LaTeX : my aim was not to build a very well structured database, but to get some code with samples on the same page (as a quick first help), chapter by chapter, from simple to complex (e. g. "simple frame"; "frame in a column" etc.) in order to access quickly to my documentation, and to help beginners like me. I feed this "database" with ConTeXt Garden samples and with test samples from the mailing-list, as long as I can understand them (I am not a mathematician, only someone who needs to print classical texts) : https://fr.wikibooks.org/wiki/ConTeXt
>
> A simple question : is it usefull to get a very quick access to a documentation where explanation is absent ? That's why the current explanation is very useful : even if you have to read full pages at length, the explanation given in the PDF documentation is an accurate information and oftenly says something which allow to lead to a solve your issue. So, it seems there is a conflict between the desire of a quick access to relevant information and the need of learning ConTeXt with patience !

One trap that a user can fall into is to make a complete style at once. 
because much works out of the box, one can delay styling and just define 
/ setup things as the document evolves.

Another trap is to start with some existing complex style. If you look 
at the manuals you'll notice that there is not that much being set up. 
Of course there are complex setups possible and we need them for complex 
xml to pdf workflows with lots of different structural elements and 
designer demands and exceptions, but that's not that common i guess.

Your wikibook approach sounds useful. I often put examples i run into 
(or make when testing new code) in the test suite that can be downloaded 
but i wonder if many users can use that (too many files).

Some kind of "if you need this, look there" system would be nice. If you 
want keywords, the i-*.xml files are a good starting point.

>
> ----- Mail original -----
> De: "Thomas A. Schmitz" <thomas.schmitz@uni-bonn.de>
> À: "mailing list for ConTeXt users" <ntg-context@ntg.nl>
> Envoyé: Lundi 10 Octobre 2016 09:57:24
> Objet: Re: [NTG-context] Ideas for improving documentation of ConTeXt
>
> On 10/10/2016 07:43 AM, Jonas Baggett wrote:
>>
>> Thanks for your encouragement ! Yes that looks like an interesting
>> challenge for me, but it is not something I am wanting to do alone
>> because of my lack of experience, at least I would need someone to coach
>> me. Actually I don't have really experience with web developpment and I
>> would at least need help for the technological choices. Having someone
>> that tells me that if I use technology X, there are module Y and Z that
>> will be a good fit is a good start.
>
> Just two small remarks:
>
> 1. there are not that many modules in ConTeXt because most of the
> functionality is in the core. If you come from the LaTeX world, you may
> expect several hundred packages, each with their own idiosyncracies and
> documentation. That's not the case here.
>
> 2. As for your documentation project, let me be honest: unless someone
> very dedicated and very knowledgeable makes a long-term commitment and
> looks after these examples, they are worse than useless. Unless there is
> very tight control, they may contain bad and/or outdated code and lead
> newcomers in the wrong direction. The context way has always been to
> avoid boilerplate templates and let users roll their own styles. Which
> makes sense since in context almost every detail can be changed easily
> via dedicated setup commands. (This is again quite unlike LaTeX and its
> document classes that predefine many details.) I have problems imagining
> a collection of sample documents that will be more than a haphazard
> bunch of fortuitous designs.
>
> Thomas
> ___________________________________________________________________________________
> 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
> ___________________________________________________________________________________
> ___________________________________________________________________________________
> 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://context.aanhet.net
> archive  : http://foundry.supelec.fr/projects/contextrev/
> wiki     : http://contextgarden.net
> ___________________________________________________________________________________
>


-- 

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------
___________________________________________________________________________________
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________