#TechnicalWriting #SoftwareDocumentation #Documentation #4doc #Diataxis: "4doc is much better than 5para: I’ve never read a halfway-decent 5-paragraph essay but I’ve read plenty of good 4doc pages. Even so, it still leads to the same kind of “this is the only way” thinking. People use the model even when it’s not the right choice and they don’t vary up the format even when they should.

My specific issue is that the model is not universal and it’s not comprehensive."

https://www.hillelwayne.com/post/problems-with-the-4doc-model/

Sarah Haïm-Lubczanski: Présentation:
Améliorons ensemble la documentation de #PostgreSQL ! avec Sarah Haïm-Lubczanski

#postgres #diataxis #postgresqlfr #pgdayfr

Discovered @EvilDMP's Diátaxis documentation framework this morning, as I plan a migration of my #DTAT 'lay outreach' blog from #WordPress to #Quarto. It shows me how little my previous #SciComm efforts have ventured outside the #explanation quadrant! Has anyone else on here adopted #diataxis for #SciComm around a #methodology?
https://diataxis.fr/

#docs #diataxis #man

Иногда проекту достаточно Readme или man. Но у https://docs.selfprivacy.org другой масштаб. Надо не только показать как продуктом правильно пользоваться, но и обучить пользователя приватному поведению. Объем работы удручает, но выход есть — https://diataxis.fr Популярный фреймворк, который помог организовать документацию для многих компаний, включая Cloud Flare. Коротко: https://github.com/evildmp/diataxis-documentation-framework/blob/main/how-to-use-diataxis.rst
Писать документацию всё равно придёться, но уже с понятными целями и задачами.

@liw Not sure if it's missing tutorials or just mixing tutorials with explanations.

Certainly has no reference material, I assume that's in a manual page?

#diataxis

@liw Not sure if it's missing tutorials or just mixing tutorials with explanations.

Certainly has no reference material, I assume that's in a manual page?

#diataxis