What nobody tells you about documentation
What nobody tells you about documentation on HackerTube: recommended by 3 Hacker News commenters across 3 separate months, 2021–2024.
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.
What HN commenters said
6 Hacker News comments link this video. Each one links back to its thread.
MaxBarracloughMar 2021Strongly recommends
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-oriented) │ (Problem-oriented) │ || ├──────────────────────────┼─────────────────────────┤ │ Discussions │ Reference │ || │ (Understanding-oriented) │ (Information-oriented) │ || Theoretical └──────────────────────────┴─────────────────────────┘ \/ <=== Useful for study Useful for coding ===> [0] ▶ this video (that will take you to the start of the talk proper) [1] [link] edit Didn't spot the link to [1] at the bottom of the article :P
in “The tree-based approach to organizing documentation sucks” · View on HN
O__________OJun 2022Recommends
____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 poorly express that 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. ____System for to Producing Tech Docs____ Anyone looking for a good system of producing documentation should check out: [link] Which has a 30-min presentation: ▶ this video Prior HN posts on the system are here: [link]
in “How to avoid being a secretary for engineers (2018)” · View on HN
O__________OJun 2022Recommends
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: ▶ this video Prior HN posts on the system are here: [link]
in “Ask HN: How to level up your technical writing?” · View on HN
ivan_ahMar 2022Recommends
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] ▶ this video
in “Ask HN: Which book can attract anyone towards your field of study?” · View on HN
O__________OJun 2022Cites it
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: ▶ this video
in “Unified theory of documentation systems” · View on HN
zahlmanDec 2024Critical
I'm a little less than impressed by the presentation here. The idea that Divio is describing here is the Diataxis framework ( [link] ), which "is the work of" ( [link] ) Daniele Procida ( [link] ). Who, incidentally, is also giving the PyCon talk in the video on the page you linked ( ▶ this video ). But I don't see anything resembling attribution for the ideas. They aren't just common industry knowledge or "received wisdom". (And the "quote" from David Laing at the top isn't really accomplishing anything, either.)
in “Every board game rulebook is awful [pdf]” · View on HN