Le 17/04/2024 à 13:57, Bruce Horrocks a écrit :
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.
- 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
___________________________________________________________________________________
