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

[Garulfo <garulfo@azules.eu>]

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
___________________________________________________________________________________