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

[Henning Hraban Ramm <texml@fiee.net>]

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
___________________________________________________________________________________