I mentioned this a few times in other posts, but I never made a full thread about this. This video explains it pretty well: https://www.youtube.com/watch?v=t4vKPhjcMZg. This site is about the...
I mentioned this a few times in other posts, but I never made a full thread about this.
This site is about the theory of writing documentation. "The Grand Unified Theory of Documentation"
In summary, documentation is split into four parts, each of them requires a distinct mode of writing:
Tutorials: lessons that take the reader by the hand through a series of steps to complete a project of some kind
How-to-guides: take the reader through the steps required to solve a real-world problem
Reference guides: technical descriptions of the machinery and how to operate it
Explanation: Explanation, or discussions, clarify and illuminate a particular topic
People working with software need these four different kinds of documentation at different times, in different circumstances.
If you can put these principles into practice, it will make your documentation better and your project, product or team more successful - that’s a promise.
Edit: I just found a different place where this information is hosted: https://diataxis.fr/. It's not just a copy paste.
Every documentation needs all of these, and personally if you had to choose one: Focus on tutorials and examples above all. No one can see how your API/Program is going to work until they see it...
Every documentation needs all of these, and personally if you had to choose one: Focus on tutorials and examples above all. No one can see how your API/Program is going to work until they see it in practice and tutorials are good to get the idea of the capabilities with in line explanations on a project basis.
I believe there is a missing part to the four, examples are perhaps the most important and a component to all of them.
That's something I noticed too. I've started adding example projects in my own repos, and I often check projects that use libraries I'm looking at. For example, here is a simple project that uses...
That's something I noticed too. I've started adding example projects in my own repos, and I often check projects that use libraries I'm looking at. For example, here is a simple project that uses my camera library. The project sets up a 5 player local multiple game. snip
As I understand it, the https://diataxis.fr link is the original, so it probably makes more sense to link there. The GitHub repo that's the source for the page you posted even says it's forked...
As I understand it, the https://diataxis.fr link is the original, so it probably makes more sense to link there.
The GitHub repo that's the source for the page you posted even says it's forked from the original GitHub repo. As far as I can tell, it doesn't contain substantively different content than the original - or am I missing something?
In any case, this seems to be a promising framework, and I'm going to try it with a few projects I'm working on this summer.
I think the .fr is new. I've been following those repo for a few months and it's the first time I notice it. Edit: Looks like it happens in April in this commit.
I think the .fr is new. I've been following those repo for a few months and it's the first time I notice it.
Edit: Looks like it happens in April in this commit.
Your comment here bumped this post up in my feed, I hadn't seen it before. I work for Canonical, and the company has been in a big push to move all of our docs to this model for the past year or...
Your comment here bumped this post up in my feed, I hadn't seen it before.
I work for Canonical, and the company has been in a big push to move all of our docs to this model for the past year or so. We call it Diataxis - I find it strange that neither this page nor the Diataxis page linked above acknowledges originating from the other, even though one must have come first.
Personally I'm a bit torn on the usefulness of the model, I'll be reading your link with great interest.
Both originated with the same creator, there's some info here: https://github.com/evildmp/diataxis-documentation-framework/issues/14#issuecomment-1170838014
\@jamesottaway Thanks for pointing it out, but it's absolutely fine! I used to work at Divio, which is where Diátaxis started life. https://documentation.divio.com has been around for years, and predates https://diataxis.fr.
I was under the impression that the Django project were the first to formalise this structure, and they in turn were largely inspired by the Python docs
I was under the impression that the Django project were the first to formalise this structure, and they in turn were largely inspired by the Python docs
I asked the creator about those points here a while ago: https://github.com/evildmp/diataxis-documentation-framework/discussions/36. Therefore, from your text: This would be a wrong understanding...
@Apos The questions you need to ask about content:
Is this content describing
practical steps, or
theoretical knowledge?
Is this content what I need for my
study (i.e. to gain knowledge and skills),
work (i.e. to apply knowledge and skills)?
A list of example projects clearly represents theoretical knowledge, not actions (so it must be either Reference or Explanation).
And also clearly serves our study (acquisition of knowledge/skills), not our work (acquisition of knowledge/skills). So therefore it must be Explanation.
Tutorials/How-to guides/Reference/Explanation should not be thought of as a list of "sections". They are forms or modes of documentation. It's not possible to add new ones, it doesn't really make sense. There are four, because that's what emerges from the two-axis arrangement it identifies around the needs of a practitioner of a craft.
Therefore, from your text:
Explanations are intended for people who already know, or are in the process of learning, your subject. It comes after the tutorial. Conceptual overviews come before the tutorial. They are for people who are getting ready to learn the subject, or for outsiders evaluating if they want to learn it.)
This would be a wrong understanding of what diataxis is. The words you add (e.g Conceptual Overviews) might be useful to think about when writing better documentation but they don't change the framework's axes.
I mentioned this a few times in other posts, but I never made a full thread about this.
This video explains it pretty well: https://www.youtube.com/watch?v=t4vKPhjcMZg.
This site is about the theory of writing documentation. "The Grand Unified Theory of Documentation"
In summary, documentation is split into four parts, each of them requires a distinct mode of writing:
People working with software need these four different kinds of documentation at different times, in different circumstances.
Edit: I just found a different place where this information is hosted: https://diataxis.fr/. It's not just a copy paste.
Every documentation needs all of these, and personally if you had to choose one: Focus on tutorials and examples above all. No one can see how your API/Program is going to work until they see it in practice and tutorials are good to get the idea of the capabilities with in line explanations on a project basis.
I believe there is a missing part to the four, examples are perhaps the most important and a component to all of them.
That's something I noticed too. I've started adding example projects in my own repos, and I often check projects that use libraries I'm looking at. For example, here is a simple project that uses my camera library. The project sets up a 5 player local multiple game. snip
I started a discussion here to probe the author.
As I understand it, the https://diataxis.fr link is the original, so it probably makes more sense to link there.
The GitHub repo that's the source for the page you posted even says it's forked from the original GitHub repo. As far as I can tell, it doesn't contain substantively different content than the original - or am I missing something?
In any case, this seems to be a promising framework, and I'm going to try it with a few projects I'm working on this summer.
I think the .fr is new. I've been following those repo for a few months and it's the first time I notice it.
Edit: Looks like it happens in April in this commit.
Also see: My problem with the four-document model
Your comment here bumped this post up in my feed, I hadn't seen it before.
I work for Canonical, and the company has been in a big push to move all of our docs to this model for the past year or so. We call it Diataxis - I find it strange that neither this page nor the Diataxis page linked above acknowledges originating from the other, even though one must have come first.
Personally I'm a bit torn on the usefulness of the model, I'll be reading your link with great interest.
Both originated with the same creator, there's some info here: https://github.com/evildmp/diataxis-documentation-framework/issues/14#issuecomment-1170838014
I was under the impression that the Django project were the first to formalise this structure, and they in turn were largely inspired by the Python docs
I asked the creator about those points here a while ago: https://github.com/evildmp/diataxis-documentation-framework/discussions/36.
Therefore, from your text:
This would be a wrong understanding of what diataxis is. The words you add (e.g Conceptual Overviews) might be useful to think about when writing better documentation but they don't change the framework's axes.