What nobody tells you about documentation

Channel:PyCon AU · Length:30:52 · Published:2017-08-06 · Views:105299

Watch on YouTube

Summary

Daniele Procida's PyCon AU 2017 talk presents a system that divides documentation into four kinds, usually drawn as four quadrants. He explains why mixing them makes docs poor and how separating them improves writing.

Why HN recommends it

HN recommends it as the best concise introduction to a practical framework for structuring documentation, the basis of what became Diataxis.

I highly recommend Daniele Procida's talk about this — HN, 2021

Python, Ruby & scripting languages · Software practice, open source & careers · Literature & writing craft

Subtitles (excerpt)

Welcome. Um, my name's Winnie and I'm here to introduce um, Danielle Prasha. He is a Django core developer. He works at DVIO and lives in Cardiff where he helps run things like um, PYF, Pyon Namibia, and Pyon UK. He's been your various degrees of success, a high school teacher, a company director, a philosophy lecturer, and some other things he does not care to mention. But what really worked was becoming a programmer a few years ago. He's been heavily involved in the international Python, Django, open-source software communities and have a special interest in open source software development in Africa. Can you please give a warm welcome to Denny [Applause] Thank you very much um uh Winnie and thank you all for being here. Um have we got is there a problem with my There we are. Okay. So that's I'm Danielle Pachida. That's me. I wish that could be my passport photograph but they won't let me have it because it's says I'm Python software. you see. So um it um so uh very briefly about me um I work for DVO a Swiss Django company. We do cloud hosting for Python and Django developers who don't want to be devops. So come and talk to me about that afterwards. I'm uh a member of the Django core development team and a board member of the Django

On Hacker News

Related to this: understanding the various types of documentation, and using them all appropriately. I highly recommend Daniele Procida's talk about this, [0] and the accompanying web page [1]. He gives a useful taxonomy of the 4 kinds of documentation. Through the power of Unicode: ┌──────────────────────────┬─────────────────────────┐ /\ │ Tutorials │ How-to Guide │ || Practical │ (Learning-ori… — MaxBarraclough, 2021-03
____Response to Article____ Engineers are rarely good at writing technical documentation, especially compared to technical writers (that is “secretaries” per author’s lingo) which by definition, should be. Engineers generally cost more than technical writers. Good technical writing saves engineering time both during AND after the documentation is produced. Author spends large amount of time, to p… — O__________O, 2022-06
To be a good technical writer, you must understand who needs what and why, then figure out how to solve that the best way based on the context. Anyone looking for a good system of producing documentation should check out: [LINK] Which has a 30-min presentation: [VIDEO] Prior HN posts on the system are here: [LINK] — O__________O, 2022-06
It's not a book but a website[1] and a talk[2] that explains a good strategy for writing docs, based on four quadrants. [1] [LINK] [2] [VIDEO] — ivan_ah, 2022-03
They’re officially related. Personally, prefer the link I used since it provides a table of contents and link to this YouTube presentation on the system: [VIDEO] — O__________O, 2022-06

Related videos