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 ___________________________________________________________________________________