At your request, https://diataxis.fr/atom.xml
830 karma · joined March 13, 2015
There is a real problem there, and that page doesn't do a good enough job of dealing with it. I have something cooking that is much, much better.
Some deliveries will be retried, but after 30+ hours some will have permanently failed.
Every company has an outage now and then, and sometimes a bad one.
But, it has now been 30 hours since I had access to my email. The last update was 15 hours ago. I don't like the way this has been handled.
That's a mistake in my opinion. The big compass of four kinds of documentation I eye-catching and memorable, and I am sure it is part of the success of Diátaxis.
But what gets me out of trouble in my own work every time is https://diataxis.fr/compass/. It's one thing to have the general idea; it's another to be armed with an effective tool to apply to work.
The site doesn't just contain opinions and ideas, it also contains tools, that really are worth using.
I worked on Django documentation and Diátaxis at the same time, so naturally you will see a lot of the same patterns.
That's different from a how-to, talking someone through a problem.
Tutorials, how-to guides, reference, explanation are modes of documentation.
They are not an exhaustive list of every kind of content that should appear in your documentation.
Diátaxis is not a list of four boxes into which all content should be mercilessly shoved whether it fits or not.
Consider: a homepage, an introduction, a foreword, a contents page, a landing page for a section, an index, credits, a list of contributors (I am sure you can think of more).
These can all be important. Documentation without a homepage would be positively stupid. I don't think we should have sections that are not introduced by landing pages.
Diátaxis doesn't prescribe anything for them, not because they are not important, but because they are not themselves modes of documentation. They are part of its furniture, if you like - just as an introduction, translator's note etc might be an important part of a book, but nothing whatsoever to do with the story it contains.
Homepages and landing pages are explicitly mentioned at https://diataxis.fr/complex-hierarchies/, by the way.
(Release notes could equally well be expressed as reference or in a section on their own. It really doesn't matter. It doesn't seem like something Diátaxis needs to worry about.)
Put it in an IKEA Ribba 30x21cm frame: https://www.ikea.com/nl/nl/p/ribba-fotolijst-zwart-60378396/. It's deep enough to accommodate the iPad and cable, so that they're hidden if the frame is stood up on a table or shelf.
Remove the plastic protection of the frame, and have a framing shop cut the mount to exactly the right size. Use double-sided tape or some other adhesive to fix the glass to the back of the mount.
It can play slideshow from a Photos album via iCloud.
It would be nice to have an elegant way to reach the front button, a problem I haven't yet solved to my satisfaction.
For an example, consider https://brachiograph.art. It's pretty imperfect documentation, but the needs of the newcomer are answered in the tutorial, along with the clear instruction: Start here. Everything else is laid out in the contents and findable there.
Good question. And:
> This framework is helpful for thinking about content
You are absolutely right, it doesn't prescribe four boxes for all content to be forced into at all costs, it describes an approach to thinking about what you are doing when you are writing and managing documentation.
As for your question: let's say you're flying an airliner, and for whatever reason, you have to make an emergency descent. You want to know what to do. You want a how-to guide. You turn to the EMERGENCY DESCENT page in the Quick Reference Handbook. It prescribes the steps to take, in the form of a list. It says: if this, then do that. You know what you want to achieve, then handbooks guides you through the actions.
A different scenario: you're at cruising altitude, and have to shut down an engine. You want to know what the situation is (what the optimum drift-down rate is, level-off altitude, and so on) given your current weight etc. You need information (reference). You'll turn to the ENGINE INOP page, where you'll read the numbers off tables. No instructions - just facts.
In either case, encountering a mixture ("pollution") of how-to prescription in the reference description (and vice-versa) would be at best unwelcome, at worst, deadly. Your needs are different in each case. You know when you want to know what you should do, and what you should know. You know when you need to flip from one to the other. Documentation should serve those needs, by keeping the material separate.
And pilots manage even without hyperlinks, which make it so much easier for our software documentation!
I would ask not so much whether it has paid off or whether there was improvement, but whether it is paying off.
We're not done yet, we have really only just got started - it's a long-term project of transformation, that starts with practice and processes and people and will eventually show up in the documentation that's produced.
You can see evidence of it already in some of our documentation, it's the work of those engineering teams that have been spearheading the efforts, but it's all work in progress and we have a long way to go. (It's also all incremental work, so in general, there won't be dramatic big bangs to show.)
What you can't see from the outside are things like mindset, priorities and understanding of documentation - those are the things that will make for long-term success.
All the same, you remind me that it's probably a good idea to follow up that article with one pointing to some visible results.
There would be much more work required before it could be applied in practice.
One confusion is about how this might be used. It's about the possibility of a very cheap and readily-available means of basic testing (not a substitute for laboratory testing) in criminal investigation.
Practical knowledge is knowing how to do something - tie your shoelaces, instantiate a model class, authenticate to an LDAP server.
Theoretical knowledge is knowing what is the case - that the cross-flow valves must be closed at take-off, that everything in Python is an object, what a Python property decorator does.
Technical reference is theoretical knowledge (that you apply in practice), as is explanation. Tutorials and how-to guide contain practical knowledge.
The scheme is not a plan that must be fulfilled, it's a guide or map to help you see where you are and where you need to go.
However, don't be ashamed of barren-looking things. They are OK. The reader won't mind.