Re: Ideas for improving documentation of ConTeXt

[Jonas Baggett <jonas17b@gmail.com>]

Le 10. 10. 16 à 09:57, Thomas A. Schmitz a écrit :

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

I wasn't thinking about ConTeXt modules here but choosing the right web 
framework that has the right modules.

> 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

Ok, thanks for pointing a possible problem with code quality. Yes it is 
something we have to think about and find a solution that will ensure 
good code quality among the examples. Here would be my vision for the 
project in 3 points :
1. It's about learning ConTeXt by examples, not only learning how to 
make the code work as expected, but to make it work the correct way.
2. Encourage a collaborative spirit so that the community is willing to 
help anyone to reach point 1 (by posting examples and making suggestion 
or improving existing examples).
3. See below
If this vision could be enough advertised to those who want to 
contribute with their examples, I believe a lot less control would be 
need, as the community will do the control itself.

Concerning outdated code, as I understood, the ConTeXt core interface is 
stable so if we add a tag for the ConTeXt Mark (II, IV, VI) that would 
do it. But for examples using modules, yes that's right, interfaces 
could change and make the existing examples outdated. So I believe that 
having in the database a description of the modules interface, will 
mitigates the problem. And when a command in a module becomes 
deprecated, then the description of the module interface needs to be 
updated and a hint could be added to fix outdated code, like : "<old 
command> is deprecated, replace it by <new command>". Then warnings will 
be added automatically on examples using outdated code with useful hints 
to fix it.

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

So if I understand well the philosophy difference between LaTeX and 
ConTeXt, the LaTeX philosophy would be about using document classes and 
avoid making much tweaks but be more focused on the content. With 
ConTeXt on the other hand, the philosophy is more about being able to 
customize everything.

Actually there could be 2 categories of ConTeXt documents on the database :
1. Those that are more aimed toward making others learn ConTeXt, like 
tutorials
2. Those who are templates.

It's very likely that the 2nd category will be more present, as I 
imagine that a typical contribution would be someone who spend some time 
with a document he has made in ConTeXt and is happy with the result and 
want to post it on the database in order to allow others to benefit from 
his work.

Indeed, the third point of my vision would be to make a big collection 
of templates available, but my goal isn't to go against the ConTeXt 
philosophy. The idea would be more like if someone has a particular 
need, he could find a suitable template in the database, take it, 
analyze it, tweak it and learn more about ConTeXt in the process. 
Templates would be also a good advertisement for ConTeXt : before 
someone could be interested in ConTeXt he has to believe that ConTeXt 
could fit his needs and that it hopefully isn't a pain to use. If he 
could find a suitable template, he would be in a very short time 
convinced that ConTeXt can do what he needs to and that it is nice to 
use thanks to its clean well-though synthax. Then he will probably 
become a new ConTeXt user.

I believe that having precise tags and allow to sort by popularity will 
help to structure the database so that it doesn't become haphazard and 
also the higher quality works will have more visibility.

Before starting any project it is good to analyze what are the 
opportunities and the risks. I was more clear about the opportunities 
than the risks, so thank you for pointing me the risks.

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