Re: Ideas for improving documentation of ConTeXt

[Hans Hagen <pragma@wxs.nl>]

On 10/10/2016 12:49 AM, Jonas Baggett wrote:
> Hello Henri,
>
>> Most probably no one else will volunteer to do it and especially the
>> people from PRAGMA surely have better things to do. They merely
>> develop and use ConTeXt (...)
> Here I don't agree. People from PRAGMA are probably better at
> developping ConTeXt than starting in parallel a new project like that,
> but it doesn't mean that this idea is necessarly not worth considering.
> I wasn't either suggesting that they should be the people who start
> implementing the idea.
>> (...) and were so kind as to provide us a huge bunch of documentation
>> already (http://pragma-ade.nl/document-1.htm).
> Yes I just saw that you are right about the documentation, they have
> already made a huge work on that. I was maybe too quick about my
> conclusion, I am sorry if I did offend those who have already make all
> that work. I was actually doing a cover letter in ConTeXt and since I
> wasn't able to find uptodate informations about some of the commands I
> was a little frustrated. But yes the letter module is third party and I
> just saw in the wiki that it is said to be still in developpment, so
> interface changes are to be expected and not necessarly all documented.
> Since I am new to ConTeXt, my views on ConTeXt documentation got biased.
> But now I am pretty happy with the results I have with my document, so
> most of the troubles are behind, I guess :-).

Don't worry, no one feels offended. FYI, Pragma is not that large a 
company so we cannot allocate more resources than we do now (and did the 
last couple of decades). We just provide the manuals we write in the 
process and happily leave the rest to others.

> On the other hand, some of the documentation still need to be updated.
> Since ConTeXt is quick to evolue, having uptodate documentation would be
> a huge task and I also understand that it may not be the most
> interesting part for developpers ;-). My proposition was about to
> mitigate that problem with making accessible examples with some advanced
> search to quickly find relevant results.

Not all old manuals will be updates. There are already a lot in the 
distribution and another 6 on my disk waiting for an mkiv update. These 
are often covering a specific aspect. I happily leave writing additional 
manuals to others.

Each year at the context meeting this topic pops op and there are many 
plans but a lack of time interferes.

Btw, Alan is writing a larger story for beginners.

> Maybe someday ConTeXt will be more mature and have a more stable
> interface, then it would be easier to have uptodate documentation. But
> it is only the analysis of someone who is only starting to know ConTeXt,
> so I won't assume to be totally correct.

The interface is actually rather stable otherwise we could not use it 
ourselves. However the move to luatex made it possible to kick out code 
related to input and font encoding as well as update to new technologies 
so there have been changes.  So, the trick is to point new users to the 
right examples and documentation.

Hans

-----------------------------------------------------------------
                                           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://tex.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________