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