Re: Ideas for improving documentation of ConTeXt

[Wolfgang Schuster <schuster.wolfgang@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4503 bytes --]

> Jonas Baggett <mailto:jonasb@tranquille.ch>
> 9. Oktober 2016 um 13:18
> Hello everyone,
>
> I am new to new to ConTeXt and I was thinking about how to improve 
> documentation to help users and then make ConTeXt more appealing. 
> Because, if there is one weak point in my eyes with ConTeXt, it is the 
> lack of documentation, which is too bad because ConTeXt seems to be 
> really great. And google search is also a little tricky, since context 
> is a common name. On the other hand, most of the help I found was on 
> the wiki, the mailing list, TeX Stack Exchange and some pdf 
> documentations. Sometimes, I also faced the problem about the 
> documentation being outdated and when I am trying to find the solution 
> on the internet, I may have a hard time finding solutions that aren't 
> outdated too. The worse is maybe when a command option isn't working 
> anymore with not even a warning.
Many of the old manuals got updates by Hans and he included the PDF’s 
(together with the source files) in the normal ConTeXt download, you can 
find them in the doc folder in your ConTeXt installation.
> The basic idea I have is a database of ConTeXt documents, where 
> everyone can add his own documents. We have also to make it easy to 
> find there insightful examples in ConTeXt that will help someone to 
> achieve what he is trying to do. Then users, especially beginners, 
> will less likely be stuck at one point and looking for hours for a 
> solution and less help will be asked on the mailing list too.
The wiki has a page for examples and you’re free to update the existing 
examples or add new ones.
> Here are the basic concepts about the database :
> - When someone adds a document, he can specify the type of the 
> document like e.g. report, letter, CV, book, etc. Subcategories could 
> be a good idea too, e.g. letters can have a subcategory called cover 
> letters. Some extra tags could also be useful, like e.g.: math, 
> luatex, tables, positioning, etc when there is some use of the 
> preceding, maybe not necessarily essential when the use is only basic.
> - If some extra fonts or modules are needed to be installed in order 
> to make the example fully work, this could also be specified.
> - Search could be done by specifying one or more categories and tags. 
> It will also be possible to search all the occurrences in the database 
> of a command with optionally a command parameter.
> - It will be like a wiki so that everyone could improve the existing 
> examples.
> - It can be also useful to allow comments, because it is possible that 
> an example is close to what someone is trying to do, in which case he 
> will look on the comments hoping that there was already someone who 
> asked there the question and got answered.
> - In order to mitigate the problem with deprecation stuffs after some 
> language changes, we could have all the commands and their options 
> listed somewhere in the database, then when a command or command 
> parameter is getting deprecated, it will be possible to mark it as so 
> and provide some hints on how to fix it. After that, all the examples 
> that use the deprecated stuffs will get a warning and hints will be 
> showed about how to fix them. And since that examples are editable by 
> anyone, there won't be hopefully very much of outdated documents.
>
> Here some are possible scenarios about searching in the database  :
> - Someone is writing a letter and is trying to move one element (e.g. 
> date, his address, receiver address) in another location without any 
> success so far. Then he will go to this database, choose letter as 
> category and positioning as extra tag and launch the search. Maybe he 
> will get about 20 results, then chances are that some of the found 
> examples will be doing something close enough to what he's trying to 
> do, so that he could analyse the source and understand what he needs 
> to do in his case.
> - Someone is looking about how to set the background color of a framed 
> box. Then he will search occurrences of the uses of the \framed 
> command which have color in their arguments. Then by looking at the 
> found examples, he will find out that the color is set with the 
> backgroundcolor argument and that the background argument need to be 
> set to "color" too.
>
> What do you think about the idea ? I believe this could be a good 
> complement to the existing ressources.
Sounds interesting and the best thing you can do is to start with it.

Wolfgang

[-- Attachment #1.2: Type: text/html, Size: 5973 bytes --]

[-- Attachment #2: Type: text/plain, Size: 485 bytes --]

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