5 ms·

This is similar to the four types of software documentation: https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/

bluGill 2y ago
Sounds good, but I'm stuck with how to apply that to my current documentation. I need a how-to right now and all I get is an explanation.
- coherentpony 2y ago
  > I need a how-to right now and all I get is an explanation. This isn't a reasonable expectation. Your current state of documentation may be very different from some-other-software's current state of documentation. There may (or may not) be commonalities across those states, but assuming the most conservative situation leaves you with no commonality and the author's only option is to write the explanation for you. From there, you have to think about what transformations you need to apply to your current state to get it to the desired state. Contrast this with game rulebooks. There is a clear commonality: situations where none of the players know any of the rules. Therefore, the rulebook can easily be written assuming no knowledge of the current rules of the game. Players that know the rules of the game can either a) go make everyone coffee and avoid polluting the learning phase with information that stretches the patience of the folks reading the rulebook; or b) claim to the players that don't know the rules that the rulebook is useless and they can do a much better job explaining all the nuances much better than the person that designed the game.
  - bluGill 2y ago
    Did you not read the link? The reference should be obvious. I'm giving the link too much credit calling it 'explanation' but it isn't even an example of what it advocates in any case.
zahlman 2y ago
I'm a little less than impressed by the presentation here. The idea that Divio is describing here is the Diataxis framework (https://diataxis.fr/ https://diataxis.fr/), which "is the work of" (https://diataxis.fr/colophon/ https://diataxis.fr/colophon/) Daniele Procida (https://vurt.eu/ https://vurt.eu/). Who, incidentally, is also giving the PyCon talk in the video on the page you linked (https://www.youtube.com/watch?v=t4vKPhjcMZg https://www.youtube.com/watch?v=t4vKPhjcMZg). 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.)
- pbh101 2y ago
  My understanding is that it is Procida’s work at Divio that was then later spun out into Diataxis, with Divio permission. Source: https://www.hillelwayne.com/post/problems-with-the-4doc-model/#fn:diataxis https://www.hillelwayne.com/post/problems-with-the-4doc-mode...
  - cratermoon 2y ago
    Also see https://buttondown.com/hillelwayne/archive/beyond-the-four-document-model/ https://buttondown.com/hillelwayne/archive/beyond-the-four-d...
  - zahlman 2y ago
    Thanks. I already had "something about Diataxis" somewhere on my blog agenda before the HN post, and between this and the rest of the comments and the article I feel like I have a lot more material now.
- strogonoff 2y ago
  I’m not that impressed with Diataxis, considering it is basically describing the approach of Django project’s docs—which (both docs and the aporoach) predate Diataxis by many years—without giving any credit that I know of. Jacob Kaplan-Moss described[0] the approach in 2009 (he omitted the How To guides, but they are in fact part of Django docs for as long as the framework is widely used). If there was a person to credit for this, that would be him. [0] https://jacobian.org/2009/nov/10/what-to-write/ https://jacobian.org/2009/nov/10/what-to-write/

bluGill 2y ago

Sounds good, but I'm stuck with how to apply that to my current documentation. I need a how-to right now and all I get is an explanation.

coherentpony 2y ago
> I need a how-to right now and all I get is an explanation. This isn't a reasonable expectation. Your current state of documentation may be very different from some-other-software's current state of documentation. There may (or may not) be commonalities across those states, but assuming the most conservative situation leaves you with no commonality and the author's only option is to write the explanation for you. From there, you have to think about what transformations you need to apply to your current state to get it to the desired state. Contrast this with game rulebooks. There is a clear commonality: situations where none of the players know any of the rules. Therefore, the rulebook can easily be written assuming no knowledge of the current rules of the game. Players that know the rules of the game can either a) go make everyone coffee and avoid polluting the learning phase with information that stretches the patience of the folks reading the rulebook; or b) claim to the players that don't know the rules that the rulebook is useless and they can do a much better job explaining all the nuances much better than the person that designed the game.
- bluGill 2y ago
  Did you not read the link? The reference should be obvious. I'm giving the link too much credit calling it 'explanation' but it isn't even an example of what it advocates in any case.

zahlman 2y ago

I'm a little less than impressed by the presentation here. The idea that Divio is describing here is the Diataxis framework (https://diataxis.fr/ https://diataxis.fr/), which "is the work of" (https://diataxis.fr/colophon/ https://diataxis.fr/colophon/) Daniele Procida (https://vurt.eu/ https://vurt.eu/). Who, incidentally, is also giving the PyCon talk in the video on the page you linked (https://www.youtube.com/watch?v=t4vKPhjcMZg https://www.youtube.com/watch?v=t4vKPhjcMZg). 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.)

pbh101 2y ago
My understanding is that it is Procida’s work at Divio that was then later spun out into Diataxis, with Divio permission. Source: https://www.hillelwayne.com/post/problems-with-the-4doc-model/#fn:diataxis https://www.hillelwayne.com/post/problems-with-the-4doc-mode...
- cratermoon 2y ago
  Also see https://buttondown.com/hillelwayne/archive/beyond-the-four-document-model/ https://buttondown.com/hillelwayne/archive/beyond-the-four-d...
- zahlman 2y ago
  Thanks. I already had "something about Diataxis" somewhere on my blog agenda before the HN post, and between this and the rest of the comments and the article I feel like I have a lot more material now.
strogonoff 2y ago
I’m not that impressed with Diataxis, considering it is basically describing the approach of Django project’s docs—which (both docs and the aporoach) predate Diataxis by many years—without giving any credit that I know of. Jacob Kaplan-Moss described[0] the approach in 2009 (he omitted the How To guides, but they are in fact part of Django docs for as long as the framework is widely used). If there was a person to credit for this, that would be him. [0] https://jacobian.org/2009/nov/10/what-to-write/ https://jacobian.org/2009/nov/10/what-to-write/