Random plug for a documentation system I really enjoy and got to talk about with someone today.
If you struggle to write (or think about) good technical documentation like I do, you might benefit from learning about Diátaxis. https://diataxis.fr/
It breaks down the different reasons people go to learn and acquire information and it really helped me think about how I want to present information.
Les Cast Codeurs en 2024 parlent du framework Diataxis et de ranger la documetnation
(Si vous préférez les formats audio)
https://lescastcodeurs.com/2024/12/21/lcc-320-diataxis-la-methode-de-documentation/
Emmanuel, Guillaume et Arnaud se rejoignent pour discuter de Diátaxis une approche pour structurer sa documentation. Ils offrent leur perspective sur leur usage et leur compréhension. Le sujet s’ouvre ensuite pour discuter des plateformes de documentation et comment l’IA impacte la documentation. Cet épisode est aussi sorti en vidéo, n’hésitez pas nous dire ce que vous en pensez des retours et souscrivez au channel YouTube 🤗.
found a very interesting framework for writing effective documentation: https://diataxis.fr
#Diátaxis and #Python #documentation
https://discuss.python.org/t/diataxis-and-python-documentation/41836
I’d like to put forward a vision for the future of Python’s documentation, as published at https://docs.python.org, in the hope of building general consensus for two things: an idea of what good means in documentation and its application to Python’s documentation in particular ways of working that will bring about significant improvements more swiftly I see a very strong opportunity to bring what I can do, to what I think Python’s documentation needs, and I would like to do more of that work ...
@echerng How about a #startup providing a #saas product that gets access to all of the company accounts where relevant information is stored, and then uses #ai to keep #documentation up-to-date for #businesscontinuity?
It could even provide it in a standard format, like #diataxis: https://diataxis.fr/
I'm open to talking about this if anyone out there is interested.
@kevinbowen Oh this is interesting. I've kept this (ish) as one of my personal principles for writing documentation, that there need to be different kinds of documentation to serve different audiences (especially: tutorial and reference docs), but I never knew there was a formal system for it.
While I haven't necessarily drank the #Diataxis #documentation kool-aid 😄 , I do think that what is going on with the #Python documentation is interesting and it is a conversation and a mind-set that it worthy of consideration & attention. YMMV
https://discuss.python.org/t/diataxis-and-python-documentation/41836
I’d like to put forward a vision for the future of Python’s documentation, as published at https://docs.python.org, in the hope of building general consensus for two things: an idea of what good means in documentation and its application to Python’s documentation in particular ways of working that will bring about significant improvements more swiftly I see a very strong opportunity to bring what I can do, to what I think Python’s documentation needs, and I would like to do more of that work ...
https://diataxis.fr/tutorials-how-to/ #diátaxis on #tutorials vs. #HowToS
«Diátaxis insists that what matters in documentation is the needs of the user, and it’s by paying attention to this that we can correctly distinguish between tutorials and how-to guides.
Sometimes the user is at study, and sometimes the user is at work. Documentation has to serve both those needs.
A tutorial serves the needs of the user who is at study. Its obligation is to provide a successful learning experience. A how-to guide serves the needs of the user who is at work. Its obligation is to help the user accomplish a task. These are completely different needs and obligations, and they are why the distinction between tutorials and how-to guides matters: tutorials are learning-oriented, and how-to guides are task-oriented.»
Greg 🌈🐻🖥️🐈
Mail Reach
Mère Teresa
Tarsis.net
xyhhx 🔻
Alexandre B A Villares 🐍
Colan Schwartz
David Zaslavsky
Kevin Bowen (has moved) 