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

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

On 15/04/2024, at 2:18 AM, Henning Hraban Ramm 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 ___________________________________________________________________________________