Skip to content
Hallway
0:00 / 0:00

#diataxis#documentation#danieleprocida

What nobody tells you about documentation

PyCon AU

25K subscribers • 2 videos on Hallway

YouTube
  • Recommended by 3 people: 3 on Hacker News.
  • Presented by Daniele Procida
  • An opinion. It argues one side of a question engineers disagree on.

Beginner. No background in the topic needed.

105K views9 years ago3 recommendations

Tools and practiceDeveloper productivityCode review and teamwork

Daniele Procida presents a systematic framework that divides technical documentation into four distinct quadrants: tutorials, how-to guides, reference, and explanation.

Daniele Procida 2017.pycon-au.org/schedule/presentation/15/ #pyconau This talk was given at PyCon Australia 2017 which was held from 3-8 August, 2017 in Melbourne, Victoria. PyCon Australia is the national conference for users of the Python Programming Language. In August 2017, we're returning to Melbourne, bringing together students, enthusiasts, and professionals with a love of Python from around Australia, and from all over the World. August 3-8 2017, Melbourne, Victoria Python, PyCon, PyConAU

Why it's here

3 people recommend this, 1 disputes it

What people say. Widely recommended as the definitive talk on how to structure and write effective technical documentation using the Diátaxis framework.

MaxBarracloughon Hacker News • Recommends

On “The tree-based approach to organizing documentation sucks”

…Tutorials │ How-to Guide │ || Practical │ (Learning-oriented) │ (Problem-oriented) │ || ├──────────────────────────┼─────────────────────────┤ │ Discussions │ Reference │ || │ (Understanding-oriented) │ (Information-oriented) │ || Theoretical └──────────────────────────┴─────────────────────────┘ \/ <=== Useful for study Useful for coding ===> 0 link to 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…
View on Hacker News

ivan_ahon Hacker News • Recommends

On “Ask HN: Which book can attract anyone towards your field of study?”

It's not a book but a website1 and a talk2 that explains a good strategy for writing docs, based on four quadrants. 1 link 2 link to this video
View on Hacker News

O__________Oon Hacker News • Recommends

On “How to avoid being a secretary for engineers (2018)”

…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: link to this video Prior HN posts on the system are here: link…
View on Hacker News

O__________Oon Hacker News • Recommends

On “Ask HN: How to level up your technical writing?”

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: link to this video Prior HN posts on the system are here: link
View on Hacker News

zahlmanon Hacker News • Disputes

On “Every board game rulebook is awful [pdf]”

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 ( link to 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.)
View on Hacker News

O__________Oon Hacker News • Mentions

On “Unified theory of documentation systems”

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: link to this video
View on Hacker News

u/elohhimin r/typescript • Mentions

On “What do you look for when testing out new projects?”

Not sure what your library is, so it might be an overkill but I would highly suggest watching this presentation about documentation system: link to this video Very eye opening about documenting software. If you prefer reading it is documented here: https://documentation.divio.com/
2View on Reddit

u/ErrorIsNullErrorin r/ProgrammingLanguages • Mentions

On “How do you like code documentation inline in the source code vs. as separate guides, or how would you do it?”

link to this video is a good talk on how to organize documentation. Perhaps some documentation is better in code, and some is better separate. Either way, one thing to learn from the Rust documentation project may be ways to automate testing of code samples in docs so they stay in sync as the code evolves. ---- TLDR. When writing documentation, a project should keep in mind that there are four kinds for (practice, theory) x (studying, practicing): diagram. The Django documentation explicitly explains the four kinds, whom each is for, and when at "how the documentation is organized" Mixing these kinds makes the documentation less effective for all consumers : "the tendency to collapse"
1View on Reddit