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 garu...@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
___________________________________________________________________________________
