Moving toward Diátaxis

by Bill Wear on 7 July 2021

We discovered the Diátaxis Framework earlier this year. It’s been on our roadmap to shift MAAS doc to this cool new way of explaining things. This cycle, we plan to make it happen.

You’d think it would be obvious….

Diátaxis is one of those ideas. Once you see it, you can’t figure out why everybody didn’t come up with this system. This framework divides documentation up into four buckets:

• Explanations
• How-to guides
• Tutorials
• Reference material

When writing, one shouldn’t mix the buckets. You should take the time to view the material for yourself — it will definitely help you document your own systems better.

Sorting the MAAS documentation into these buckets requires some clear delimiters. We’re currently taking a liberal approach, but here’s what we’ve come up with so far:

• Explanations assume that the reader is familiar with common technical terms, like “DHCP” or “network bonding.” These sections will only explain MAAS terminology, features, usage, and nuances.
• How-to guides should be a little more than just steps. We’ve tried these guides a bit with MAAS 3.0, discovering that it’s possible to make them too sparse. We’ll keep a reasonable amount of compact explanation in these sections, so that you don’t have to consult the explanations too often.
• Tutorials will be full-on, newbie explanations, probably tiered with detail sections that let you skip the most basic topics, if desired. These will most likely be added to the Tutorial link, which is separate from the documentation.
• Reference material should allow us to unburden a lot of the more technical pages of long, complicated listings and tables (think “commissioning scripts” and “power types,” for example). Since the documentation is a hyperlinked medium, it’s only legwork to link the various technical details from a reference page to the other types of material.

Along the way, we also plan to simplify the navigation column on the left-hand side of the docs page. Our main issues there are: (1) that the objects in the navigation aren’t all objects; (2) that they aren’t the same kinds of objects; and (3) that the navigation structures aren’t parallel constructs, which is really important for headings and lists. Readers have trouble finding context if you group things that aren’t parallel, like this:

• Clean the garage.
• There’s some mail lying on the counter that I don’t know what to do with.
• What is all that stuff in the back of the fridge?
• Dinner is at Suzie’s at eight.

And yet, our current menu has, over time, organically become like that overgrown to-do list. Time to fix that.

Speaking of context

By implementing Diátaxis, we’re hoping to improve the flow of documentation, which is just another way of saying that we don’t want to constantly change the reader’s context. In this case, context refers specifically to a mindset or a level of focus. Much computer documentation is terrible about pushing the reader’s context all over the place.

For example, if you’re focused on following some steps to create a new virtual machine and deploy it, you’re in what might be called a “get-it-done” context. You don’t want to have to read a detailed explanation of how something works when only about five percent of that deep reading is even important to you right now. And you don’t want to view a long list or table of things you could do. What you want at this moment is a set of concrete steps to get you from A to B, with just enough explanation to keep you from tripping over the setup.

On the other hand, when you’re in deep reading mode, you may or may not be sitting right by the system, and you may or may not want to try every operation before reading on. That type of discussion is more tutorial in nature. Similarly, when you do want to look at that long list of parameters, you’d like to avoid four-page, rambling, technical explanations of every possible nuance related to something that might be related to those parameters.

In other words, if we change your context too many times, you’ll stop reading and just try something. When that doesn’t work, you may scan the doc again once or twice, but pretty soon, you’ll be on our MAAS discourse page, asking for someone to decode it all for you. There’s nothing wrong with MAAS discourse — it’s a great forum, and lately, one of our team members is always tasked with patrolling it as a top priority. But around eighty-five percent of your information needs should be met by the documentation.

So that’s the latest from the MAAS doc world. You’re welcome to comment with your thoughts on documentation structure and format.