[NTG-context] Re: Wiki - test/proposal to further clarify documentation

[Peter Hopcroft via ntg-context <ntg-context@ntg.nl>]

It would be great if the main page actually said what Context does. 

> On 15/04/2024, at 2:18 AM, Henning Hraban Ramm <texml@fiee.net> wrote:
> 
> Hi Garulfo,
> 
> I’m not against the “new order”, but I’d keep the colorful subject tiles. Different accesses are good IMO (as long as it doesn’t get to convoluted).
> 
> I’d say updating, sorting, restructuring pages is more important than a new start page.
> 
> Yes, please sort out reference vs. tutorials!
> 
> Often examples make sense in the reference pages, so the distinction is a bit fuzzy, but there are enough where a subject/tutorial page would make more sense than examples spread over several single command pages.
> 
> We could also define if the “main” reference page (with examples) is \definestuff, \setupstuff, or \stuff – IMO \setupstuff makes the most sense, since usually the others inherit from it.
> 
> Often enough, parameters aren’t explained in the reference pages; sometimes you can find examples using them, but there are too many holes. I tried to fix that where I could, but too often I don’t understand enough of the sources to make sense of some setting.
> 
> For wiki contributors, it might make sense to combine the markup pages – in many pages e.g. <texcode> is used where <context src="yes"> would make more sense; often \starttext … \stoptext is not necessary and just blows up examples; markup is generally somewhat chaotic (e.g. <tt>, <code>, or ``?).
> 
> Hraban
> 
>> Am 14.04.24 um 13:21 schrieb garulfo@azules.eu:
>> I just discover the Diátaxis documentation framework :
>> - https://www.diataxis.fr/
>> - 30min video : "What nobody tells you about documentation", https://www.youtube.com/watch?v=t4vKPhjcMZg  , from Daniele Procida at PyCon 2017
>> As I understand it, it can help both readers and writers of the documentation by clarifying the purpose of each element.
>> So I started a potential new "welcome page" :  https://wiki.contextgarden.net/Main_Page2
>> The main lines would be :
>> - Tutorials: installation pages, step by step examples
>> - How-to guides: most of the existing wiki pages which are not https://wiki.contextgarden.net/Commands/ ...
>> - Discussions and manuals: most of the existing manuals
>> - Reference : the pages dedicated to commands which already include link to mailing list, stack exchange, ConTeXt's source
>>   - https://wiki.contextgarden.net/Category:Commands
>>   - https://wiki.contextgarden.net/Special:PrefixIndex?prefix=Command%2F
>> To match the logic of Diátaxis, maybe some material from command pages should be moved from "Reference" to "How-to guides",
>> for example, when the examples go beyond "pure description" and begin to deal with "how-to" cases, e.g. :
>> - Reference for setuphead: https://wiki.contextgarden.net/Command/setuphead
>> - How-to guides for headings: https://wiki.contextgarden.net/Titles
>> If it make sense, and according to your feedbacks, I can continue to reallocate existing contents.
>> Thanks for your feedback and thoughts.
>> Garulfo
>> ___________________________________________________________________________________
>> If your question is of interest to others as well, please add an entry to the Wiki!
>> maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
>> webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
>> archive  : https://github.com/contextgarden/context
>> wiki     : https://wiki.contextgarden.net
>> ___________________________________________________________________________________
> 
> ___________________________________________________________________________________
> If your question is of interest to others as well, please add an entry to the Wiki!
> 
> maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
> webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
> archive  : https://github.com/contextgarden/context
> wiki     : https://wiki.contextgarden.net
> ___________________________________________________________________________________
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________