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.
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.