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.
> 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!
Brilliant. Only on HN will get ask a question and get an answer from the author of the original document. Completely freakin' cool.
While I have you, I'd like to ask a follow-up question that's always bothered me. How do you make documentation structured this way "beginner friendly"? It seems to me like advanced users love this kind of segmentation of content, but it's tough as a new user to find relevant sections, both for getting an initial understanding and then for problem solving for specific tasks early in their user journey.
Do you have any tips for structuring documentation in such a way that you can follow the Diátaxis 4-type model while also making content discoverable? Examples would be great as well. Just tying to draw inspiration for a project I'm currently working on.
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.
Hello, it's me, the author of the article. Thanks for asking.
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.
I'm sure there's an official place I could ask this, but since you are here, maybe you could get some more detailed examples in place for the autoinstall [0] docs?
Specifically I'm about to try using the apt section, and I'm not exactly sure how to translate the curtin docs to the autoinstall format... Especially when it comes to adding keys. And a comment about needing to use exact bytes for normal partitions in the storage section would have saved me a few hours the other day... :)
Oh, and thanks for linking to that Diátaxis framework. I might have use for that at work.
The people who are commenting that this is not something that could be used in a real-world situation are absolutely right. However, that's not what it's for - it's a study to determine whether the basic principles might be workable at all.
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.
