HackerTube.dev

What nobody tells you about documentation

PyCon AU · 105.1K views · 2017-08-06 · 30:52

Open on YouTube ↗

If playback is restricted in your region, try opening the original video. Use Mark watched to add it to your marked videos.

Overview

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.

On Hacker News

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

Recommended by 3 HN people across 3 months · HN mentions 2021–2024

Topics

Software practice, open source & careersPython, Ruby & scripting languagesLiterature & writing craft
Search by tags
documentationdiataxistechnical writingtutorialspycon

What people said

MaxBarraclough · 2021-03 · Strong recommendation

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] [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

Read the original HN comment ↗
O__________O · 2022-06 · Recommendation

____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: [VIDEO] Prior HN posts on the system are here: [LINK]

Read the original HN comment ↗
O__________O · 2022-06 · Recommendation

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]

Read the original HN comment ↗

Sources

Video by PyCon AU, played through YouTube.

Data and selection notes

HN summaries and labels may contain AI errors. HN dates refer to discussions, not video publication.

HN Library: HackerTube export (2026-10-31) and open-index/hacker-news. Upstream summaries and classifications may contain AI errors.

Views, duration and playback status refresh separately from the published catalog. When an update fails, existing data remains visible.

Selection checks
  • SaaS & AI candidates: Topic keywords do not match
  • Editor-approved picks: Editorial review is required

Rule matches identify candidates. They do not guarantee video quality or financial results.

About the library and its sources