If creators of documentation are prepared to sacrifice its human purpose in order that LLMs can more effectively slurp it up and regurgitate it on demand, then they have meekly accepted values that more properly belong in a dystopian horror story.
I have just been able to log in to my IMAP account. Only one new message in there, from two minutes ago - which suggests that all messages to me have not even reached the inbox yet.
Some deliveries will be retried, but after 30+ hours some will have permanently failed.
I have had excellent service and support from Gandi for several years. I appreciated having an EU-based provider that seemed to take pride in having a sustainable approach to the business. There was clarity about pricing. It wasn't the cheapest but they were straightforward and honest in communications.
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.
> Also (separate complaint), whenever I want to tell anyone else about this "four kinds of documentation" approach, I always link to the archived https://web.archive.org/web/20200312220117/https://www.divio... which is the latest version that is entirely on a single page.
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.
FAQ lists are the equivalent of the box in my garage where I put things when I've been told to get them out of the house, and I can't actually be bothered to put them in the right place.
Examples in reference material are an excellent idea, and not at all in contradiction to the principles of Diátaxis. An example illustrates - like an illustration in any other reference guide - and provides something concrete to help grasp what's being described.
That's different from a how-to, talking someone through a problem.
The current title of this above ("Twelve rules for for job applicants at Canonical") isn't quite right. It's just supposed to be "Twelve rules for job applicants", and no "for for" either...
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.
(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.)
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.
I'd say it's the other way round. If you follow the Diátaxis model, and keep thinking about your material according to its principles, you will find that the structure starts to emerge.
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.
> 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!