> On 14 Apr 2024, at 12:21, garu...@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 ___________________________________________________________________________________
