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

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

[garulfo]

Hi all,

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
___________________________________________________________________________________

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

[Henning Hraban Ramm]

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
___________________________________________________________________________________

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

[Peter Hopcroft via ntg-context]

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
___________________________________________________________________________________

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

[Henning Hraban Ramm]

Am 14.04.24 um 21:45 schrieb Peter Hopcroft via ntg-context:
> It would be great if the main page actually said what Context does.

In my poster (still WIP) I wrote:

start
---

The “infamous” alternative to LaTeX

While most designers use graphical tools, there are still areas where 
code-based typesetting systems are fun, make sense or are even superior. 
While LaTeX is the most known of these, ConTeXt is used by a growing 
minority of ambitioned enthusiasts around the world.

The small but active and creative community of ConTeXt users and 
developers is always driving TeX development over new frontiers:
NTS, MetaFun, Oriental TeX, LuaTeX, mplib, LuaMetaTeX…
They’re also dubbed the incisors (AKA cutting edge) of the dinosaur of 
Open Source.

ConTeXt is aimed at creative users, known for advanced features like 
extensive font control and direct XML processing, with a deep 
integration of Lua and MetaPost.

---

ConTeXt was invented in the 1990s by Hans Hagen and Ton Otten of the 
Dutch company “Pragma Advanced Document Engineering” for typesetting 
schoolbooks. Taco Hoekwater refactored the TeX source code to create 
LuaTeX which was further developed into LuaMetaTeX by Hans Hagen (and 
lately Mikael Sundqvist for refined math typography).

---

“To be fair, switching to the ConTeXt way of thinking and doing things 
was not an overnight process […]. But once I got used to it, I could not 
imagine going back to LaTeX. I’ll go even further and say that, in my 
view, ConTeXt is the future of TeX.
(Prof. Idris Samawi Hamid, 2009)
Source: www.tug.org/interviews/hamid.html

---

“ConTeXt is LaTeX done right. It is simple, flexible and powerful.”
(J. U. Hasecke on Mastodon, 2022)

---

Is ConTeXt for me?

If you want …
* to design your own layout
* best quality math typesetting
* to use Lua functions e.g. for processing data
* deep integration of a graphics language (MetaPost)
* to process XML input
* no package conflicts
* to use OpenType features
* consistent setup commands
* to place stuff on layers
* visual debugging features
* to have a lean, but mighty TeX system
* to typeset much faster than with LaTeX
* high quality Arabic typography
… then ConTeXt is for you!

---
stop

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

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

[Peter Hopcroft via ntg-context]

> On 17/04/2024, at 7:11 AM, Henning Hraban Ramm <texml@fiee.net> wrote:
> 
> In my poster (still WIP) I wrote:
> …

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

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

[Thomas A. Schmitz]

> On 16. Apr 2024, at 21:56, Peter Hopcroft via ntg-context <ntg-context@ntg.nl> wrote:
> 
> 
> 
>> On 17/04/2024, at 7:11 AM, Henning Hraban Ramm <texml@fiee.net> wrote:
>> 
>> In my poster (still WIP) I wrote:
>> …
> 
> Excellent

No, I must admit I don’t like the first two paragraphs. The question is “what is ConTeXt,” and the answer is “we’re not LaTeX.” And why “infamous”? 

Thomas

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

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

[Hans Hagen]

On 4/17/2024 8:32 AM, Thomas A. Schmitz wrote:
> 
> 
>> On 16. Apr 2024, at 21:56, Peter Hopcroft via ntg-context <ntg-context@ntg.nl> wrote:
>>
>>
>>
>>> On 17/04/2024, at 7:11 AM, Henning Hraban Ramm <texml@fiee.net> wrote:
>>>
>>> In my poster (still WIP) I wrote:
>>> …
>>
>> Excellent
> 
> No, I must admit I don’t like the first two paragraphs. The question is “what is ConTeXt,” and the answer is “we’re not LaTeX.” And why “infamous”?
I agree. It sounds the same as "we're not msword" or "we're not google 
docs". (In the end the only thing that latex and context have in common 
is that they use the tex language / ecosystem.)

Hans

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------

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

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

[Henning Hraban Ramm]

Am 17.04.24 um 10:36 schrieb Hans Hagen:
> On 4/17/2024 8:32 AM, Thomas A. Schmitz wrote:
>>
>>
>>> On 16. Apr 2024, at 21:56, Peter Hopcroft via ntg-context 
>>> <ntg-context@ntg.nl> wrote:
>>>
>>>
>>>
>>>> On 17/04/2024, at 7:11 AM, Henning Hraban Ramm <texml@fiee.net> wrote:
>>>>
>>>> In my poster (still WIP) I wrote:
>>>> …
>>>
>>> Excellent
>>
>> No, I must admit I don’t like the first two paragraphs. The question 
>> is “what is ConTeXt,” and the answer is “we’re not LaTeX.” And why 
>> “infamous”?
> I agree. It sounds the same as "we're not msword" or "we're not google 
> docs". (In the end the only thing that latex and context have in common 
> is that they use the tex language / ecosystem.)

In my experience, most people interested in ConTeXt know LaTeX, so it 
makes sense to compare.
And I actually just say “LaTeX is the most known command-based 
typesetting system” (that’s just true) to shortcut explaining what a 
cbts might be.

Your critique applies to JUH’s quote, though.

I used “infamous” as a funny way to say “not famous, but somewhat known” 
(and yes, I know Latin and what the words really mean).

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

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

[Joaquín Ataz López]

> I used “infamous” as a funny way to say “not famous, but somewhat 
> known” (and yes, I know Latin and what the words really mean).
That was my understanding. Infamous=Not famous; that is, not as well 
known as others. A slight play on words.


-- 

Joaquín Ataz López
Departamento de Derecho civil
Universidad de Murcia - España

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

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

[jbf]

Unfortunately, despite all that has been said, we have to realise what 
words actually mean in English, and 'infamous' has a negative 
connotation. So I recommend rephrasing this and perhaps the entire 
paragraph so that it presents a positive perspective on ConTeXt. But if 
you mean 'less known' then simply say that: ConTeXt is the less known 
alternative to LaTeX. and rather than 'growing minority', say 'growing 
number'. We do not say 'ambitioned enthusiasts' in English, but we could 
say 'ambitious enthusiasts'.

Julian

On 17/4/24 19:10, Joaquín Ataz López wrote:
>
>> I used “infamous” as a funny way to say “not famous, but somewhat 
>> known” (and yes, I know Latin and what the words really mean).
> That was my understanding. Infamous=Not famous; that is, not as well 
> known as others. A slight play on words.
>
>
___________________________________________________________________________________
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
___________________________________________________________________________________

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

[Bruce Horrocks]

> On 14 Apr 2024, at 12:21, garulfo@azules.eu wrote:
> 
> Hi all,
> 
> I just discover the Diátaxis documentation framework :

I'd be more confident if you had started by saying "I've been using the Diátaxis for the last ten years and have used it on multiple projects". ;-)

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

I'm going to be devil's advocate and say that the Context documentation is *already* in the Diátaxis framework - just not in one place on the Wiki.

- There are at least two books, and a third being written but not yet released: these fit into the Tutorials and Explanation quadrants.

- There are "My Way" guides linked from the Wiki and the PragmaADE website that fit into the "How-To Guides" quadrant.

- And the wiki itself is the "Reference" quadrant.

Clearly these can always be better but they are there already. My recommendation would be to use the wiki as the reference quadrant and, apart from the first few "main pages" for people who land there from a web search, it should focus on being the reference manual. Beginners should be directed to the books.

Regards,
—
Bruce Horrocks
Hampshire, UK

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

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

[Henning Hraban Ramm]

Am 17.04.24 um 13:57 schrieb Bruce Horrocks:
> - There are at least two books, and a third being written but not yet released: these fit into the Tutorials and Explanation quadrants.

Which published books do you mean?

I know of Alan Braslau’s book, AFAIK that will be published in French 
“soon” and probably later in English.
My German book is still not ready, while I work on it regularly.

Of course there are a lot of PDFs (most with sources), not only in the 
distribution, but also in 
https://github.com/contextgarden/not-so-short-introduction-to-context

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

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

[Bruce Horrocks]

> On 17 Apr 2024, at 13:17, Henning Hraban Ramm <texml@fiee.net> wrote:
> 
> Am 17.04.24 um 13:57 schrieb Bruce Horrocks:
>> - There are at least two books, and a third being written but not yet released: these fit into the Tutorials and Explanation quadrants.
> 
> Which published books do you mean?

Not published in the sense of having an ISBN assigned but the ones I had in mind were:

- "ConTeXt Mark IV An Excursion" by Ton Otten (ma-cd-en.pdf in the distribution)
- "A not so short introduction to ConTeXt Mark IV" by Joaquín Ataz-López

and your in-progress one.

Regards,
—
Bruce Horrocks
Hampshire, UK

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

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

[Garulfo]

Le 17/04/2024 à 13:57, Bruce Horrocks a écrit :
> 
> 
>> On 14 Apr 2024, at 12:21, garulfo@azules.eu wrote:
>>
>> Hi all,
>>
>> I just discover the Diátaxis documentation framework :
> 
> I'd be more confident if you had started by saying "I've been using the Diátaxis for the last ten years and have used it on multiple projects". ;-)
> 
>> - 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.
> 
> I'm going to be devil's advocate and say that the Context documentation is *already* in the Diátaxis framework - just not in one place on the Wiki.
> 
> - There are at least two books, and a third being written but not yet released: these fit into the Tutorials and Explanation quadrants.
> 
> - There are "My Way" guides linked from the Wiki and the PragmaADE website that fit into the "How-To Guides" quadrant.
- thank you for these reminders

> - And the wiki itself is the "Reference" quadrant.

> Clearly these can always be better but they are there already. My recommendation would be to use the wiki as the reference quadrant and, apart from the first few "main pages" for people who land there from a web search, it should focus on being the reference manual. Beginners should be directed to the books.

- Thanks again, the comments are helping to identify a robust method of 
distributing content across the quadrants.

- exactly, it's not a question of proposing new documents, but of 
proposing another complementary way of accessing and browsing existing ones.

- Actually, the wiki is (or can be) a hub for the 4 needs:
   - "Reference" like https://wiki.contextgarden.net/Command/setuphead
   - "How-To Guides" like https://wiki.contextgarden.net/Titles
   - "Tutorials":
	- hosted https://wiki.contextgarden.net/Detailed_Example
	- linked https://github.com/mpsmath/stepbystep
   - "Explanation" : mostly linked manuals and books


https://wiki.contextgarden.net/Command/setuphead
and https://wiki.contextgarden.net/Titles
are examples of how difficult it can be to understand where to find a 
particular information.

It might be worth keeping only the key examples on reference pages
like https://wiki.contextgarden.net/Command/***
and moving the "how-to" examples to a separate page (or pages).

> 
> Regards,
> —
> Bruce Horrocks
> Hampshire, UK
> 
> ___________________________________________________________________________________
> 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
___________________________________________________________________________________

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

[Henning Hraban Ramm]

Am 17.04.24 um 23:25 schrieb Garulfo:
> - exactly, it's not a question of proposing new documents, but of 
> proposing another complementary way of accessing and browsing existing 
> ones.
> 
> - Actually, the wiki is (or can be) a hub for the 4 needs:
>    - "Reference" like https://wiki.contextgarden.net/Command/setuphead
>    - "How-To Guides" like https://wiki.contextgarden.net/Titles
>    - "Tutorials":
>      - hosted https://wiki.contextgarden.net/Detailed_Example
>      - linked https://github.com/mpsmath/stepbystep
>    - "Explanation" : mostly linked manuals and books
> 
> 
> https://wiki.contextgarden.net/Command/setuphead
> and https://wiki.contextgarden.net/Titles
> are examples of how difficult it can be to understand where to find a 
> particular information.
> 
> It might be worth keeping only the key examples on reference pages
> like https://wiki.contextgarden.net/Command/***
> and moving the "how-to" examples to a separate page (or pages).

I agree. Let’s accept this as a rule for further wiki editing.

Also, explain parameters with top priority in Command/setup* pages 
(keeping them in Command/define* pages etc. doesn’t hurt, but at least 
experienced users should know where to find something without searching).

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

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

[garulfo]

I have tested on 2 pages :
- https://wiki.contextgarden.net/Sciences (only mathematics part)
- https://wiki.contextgarden.net/Fonts

After these tests, I think this may help users to find their way around the various sources of documentation :
In one small table he/she has an overview of the documentation for a given topic,  :
- the few key tutorials
- link to one "main wiki page" about the topic
- the few key manuals
- the reference for commands

I'm not sure I've selected the few documents that are considered by the community as the key tutorials.
Thanks for your feedback again.

PS : in order to benefit from mediawiki page organization features, I moved some pages, for example
wiki.contextgarden.net/blablabla
==> wiki.contextgarden.net/Topic/blablabla
___________________________________________________________________________________
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
___________________________________________________________________________________

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

[Bruce Horrocks]

On 17 May 2024, at 21:40, garulfo@azules.eu wrote:
> 
> I have tested on 2 pages :
> - https://wiki.contextgarden.net/Sciences (only mathematics part)
> - https://wiki.contextgarden.net/Fonts
> 
> After these tests, I think this may help users to find their way around the various sources of documentation :
> In one small table he/she has an overview of the documentation for a given topic,  :
> - the few key tutorials
> - link to one "main wiki page" about the topic
> - the few key manuals
> - the reference for commands

The fonts page is a lot better than before[1], IMHO. I would prefer the table were 90% width rather than 50 but that is minor.

So is the plan to go through each of the main headings in the left side-bar and make the same type of change?

> 
> I'm not sure I've selected the few documents that are considered by the community as the key tutorials.
> Thanks for your feedback again.

I don't think that is a problem - the Wiki can be updated by others as long as the layout/structure of the page is clear so people know where to add links.

> PS : in order to benefit from mediawiki page organization features, I moved some pages, for example
> wiki.contextgarden.net/blablabla
> ==> wiki.contextgarden.net/Topic/blablabla


[1] Previous style for reference: <https://web.archive.org/web/20231116125758/https://wiki.contextgarden.net/Fonts>
—
Bruce Horrocks
Hampshire, UK

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

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

[garulfo]

> So is the plan to go through each of the main headings in the left side-bar and make the same type of change?
Yes. 

Maybe new ones will have to be added
___________________________________________________________________________________
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
___________________________________________________________________________________