What nobody tells you about documentation
Channel:PyCon AU · Length:30:52 · Published:2017-08-06 · Views:105299
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
- Spinning Levers - How A Transmission Works (1936) · US Auto Industry · 9:40
- Constraints Liberate, Liberties Constrain — Runar Bjarnason · Scala World · 51:39
- The determinant | Chapter 6, Essence of linear algebra · 3Blue1Brown · 10:03
- Doug McLean | Common Misconceptions in Aerodynamics · Michigan Engineering · 48:25
- Zig: A programming language designed for robustness, optimality, and clarity – Andrew Kelley · Recurse Center · 54:13
- Eigenvectors and eigenvalues | Chapter 14, Essence of linear algebra · 3Blue1Brown · 17:15
- Siggraph2019 Geometric Algebra · Bivector · 1:37:21
- Revealed: ExxonMobil’s lobbying war on climate change legislation · Channel 4 News · 8:52
- Swami Sarvapriyananda at IITK - "Who Am I?" according to Mandukya Upanishad-Part 1 · Vivekananda Samiti, IIT Kanpur · 1:27:07
- Nima Arkani-Hamed: The End of Space-Time · Max-Planck-Institut für Physik · 49:42
- Ruby Conf 12 - Y Not- Adventures in Functional Programming by Jim Weirich · Confreaks · 53:21
- The spelled-out intro to neural networks and backpropagation: building micrograd · Andrej Karpathy · 2:25:52
- How Python was Shaped by leaky Internals, Armin Ronacher, Flask framework · Видео с мероприятий {speach! · 49:55
- RailsConf 2014 - All the Little Things by Sandi Metz · Confreaks · 38:47
- LEADERSHIP LAB: The Craft of Writing Effectively · UChicago Social Sciences · 1:21:51
- What the heck is the event loop anyway? | Philip Roberts | JSConf EU · JSConf · 26:52