When adapted for the needs of a general user audience, Diátaxis can be an extremely useful framework to determine the who, what, when, where, why, and how of support content.
An important callout here, my focus and area of expertise is support content. Due to the nature of this topic, I’ll be clarifying what that means throughout the article, but here’s a quick definition:
Support content describes any supplementary content which aims to support someone’s ability to use a product or service.
I’m fully aware that this definition might overlap with how some define technical documentation. Or technical writing for end-users. Or knowledge management. There are a lot of names for this practice, and that’s a topic for another day.
Before we dive in, you’ve been warned: this article gets LONG.
There’s a reason Diátaxis has a full website dedicated to it. This post more or less follows my process of understanding the framework from theoretical terms into the more practical. There are lots of links to jump around (here and throughout the article). If you’re on a desktop, there should be a navigation panel to the right. So please feel free to jump around, maybe use a desktop, and let’s get into it!
- Exploring the original theory:
- Adapting the framework:
- Applying the new framework:
- Final thoughts and does it deserve a name?
A few key takeaways/TL;DR
A parting thought before you embark on this hefty journey:
This article presents a new take on an existing idea, which is a bit scary to put out there. Apologies for any areas where I have not caught and removed my overly-defensive tangents. (This might be a remnant of one…) Have fun!
Exploring the existing theory
Before diving into my interpretation of Diátaxis, it might be helpful to give you a brief idea of what it is and why it doesn’t work for my documentation needs. I’m comfortable saying that Diátaxis is an objectively useful framework, but it’s most helpful for a very specific type of user and writer. So I’ll also get into defining very similar yet different documentation practices.
To add, these next two sections should give you an idea for whether my approach to adapting this framework might work for your needs. (That’s another warning that this post is a long one, you’ve been informed.) If you already understand Diátaxis and prefer to skip around, here’s a quick link to how I distinguish support content and tech writing or a quick link to the next section about adapting the framework.
What is Diátaxis?
Diátaxis provides a systematic framework for thinking about and working with documentation. The term Diátaxis comes from the Ancient Greek δῐᾰ́τᾰξῐς: dia (“across”) and taxis (“arrangement”).
Daniele Procida developed the Diátaxis framework in an effort to solve the problem of structure in documentation. He identifies four key forms of documentation (Tutorials, How-to guides, Reference, Explanation) and effectively maps them across four distinct user needs (action, cognition, acquisition, and application). If we apply the user needs as a compass to the map of the documentation types, we get a lovely visual:
If I try to fully explain Diátaxis here, I’m going to fall into my dozenth rabbit hole about it. Luckily, some great resources about this framework already exist. Here are my favorites if you’d like to learn more!
- The source itself: https://diataxis.fr/
- The Content Wrangler also hosted Procida for a talk: Introducing the Diátaxis Approach to Technical Documentation
- Tom Johnson’s deep exploration and how it compares to other technical writing practices in his blog post: What is Diátaxis and should you be using it with your documentation?
The most important things (bolded) to keep in mind for now (and that I wish I’d better understood sooner):
Diátaxis is intended to provide informative documentation to users who are practitioners in a domain of skill.
Support content vs technical documentation
Why are things different for support content and technical documentation?
And why does this matter? (Feel free to jump to a TL;DR of this section)
Well, if you chose to poke around some of the linked Diátaxis resources, you may have felt that there were some very big words and some mildly confusing use cases. At least that was my experience at first. I could tell it made sense from the start, but required some mental gymnastics to really make the concepts click.
The one person who immediately understood the point and put it into practice right away? Nick Cannariatio, a brilliant developer working on documentation for his new product, Yetto. As he was half-listening to me describe Diátaxis to someone else while reading about it on his own, you could see the lightbulb clicking on. (And if you are like Nick and had his experience, I see you, you’re amazing, I wish I had your brain, but I gotta make this work for me.)
These different initial reactions are no accident. Ultimately, Diátaxis was developed for users like Nick.
Technical documentation is intended to serve developers and other technical professionals who are looking for documentation directly related to their skillset. When you cannot predict the background skill of the user (and would most safely assume that there is no skill), those needs might not serve that specific user audience anymore.
Here’s a paraphrased moment from one of my chats with Nick that might help get to the point. We were talking about Diátaxis via the cooking examples on diataxis.fr, and I was feeling good about some of it:
Maring: I totally see how a recipe is an obvious how-to guide and a cooking lesson is a tutorial. I can even see how a book about cooking history is a useful explanation. But why would anyone need to know the list of ingredients on a product? How is that a user need, and how is it useful to anyone?
Nick’s response: Maybe not for a home cook, but it’s incredibly necessary for someone cooking in a professional capacity.
Duh. The type of user is key to the distinction here. The needs of a professional chef are going to be very different than those of a home cook; the professional is going to want and need more technical information.
Just like in the cooking world, most organizations are going to be faced with one or more types of users. One user audience needs the technical back-end details to do their job; another may only need the basic information to use a product (which may or may not help them do their job).
Let’s break down these user audiences within tech a little more clearly. I find the key differences lie in our assumptions of their existing knowledge, their intended task, and who at the organization best understands (and cares) about them.
A technical user:
A general user (or end-user):
There can certainly be some audience crossover here:
I like to bake at home and took up sourdough last year. If you’ve ever tried to bake bread, let alone sourdough, you start to need more technical information pretty quickly after a few weird loaves. A baker was likely always paying attention to the protein content of flour for different baked goods; I never looked past ‘all-purpose’ until I started my sourdough journey.
I went from ignoring every mommy-blogger story online to absorbing every tip they added. The bread-focused blogs have so much more than recipes with a story attached, and it’s likely because they know their readers (or users) need them. I’ve naturally gravitated toward resources that get technical, but still cater to a non-professional audience. (I LOVE the Pantry Mama, btw)
If your product or service requires more technical knowledge for a less technical user-base (from Zendesk to Zapier or Github), be aware of that! You may need to find ways to incorporate more types of documentation to serve your users; don’t ignore one user type over another!
To be clear, the core of a cook’s needs, whether professional or amateur, are not going to differ all that much. We’re all still humans with brains that function in similar ways.
That’s likely why many content practitioners, regardless of their specialty, tend to find ways to make Diátaxis work for their needs shortly after discovering it. Diátaxis is an incredibly useful framework for thinking about informative documentation and user needs. It just never seems to work consistently when applied to documentation that’s intended for a general user audience.
And here’s the TL;DR of this section:
We have to remember the thing I missed early (because of course I didn’t read the foundations page until after my fixation was in full force):
Diátaxis serves practitioners in a domain of skill.
Support content, however, is less focused on any specific type of user and more focused on helping any user complete tasks related to a specific product or service. That difference in audience is ultimately the distinguishing factor between technical documentation and support content.
So here’s an updated version of my support content definition:
Support content describes any supplementary content which aims to support someone’s ability to use a product or service [as it was designed to be used].
With this in mind, the focus and delivery of the documentation that can meet those task-focused needs are going to be a bit different.
Adapting the framework
I fully subscribe to the idea of thinking about documentation around user needs, obviously. That core idea isn’t changing, regardless of the user audience. What I did need to adjust were two specific areas of the framework that caused the most friction when applying it to support content:
Each of these ideas are a bit more complex than they sound, but ultimately come down to thinking about Diátaxis and structure less literally + clearly defining the axes of the quadrant map to adjust the user needs (and add some business needs). If you don’t want to get into the details and prefer to skip to practical applications and my updated visual, here’s a quick link to the next section.
Diátaxis and structure
Diátaxis proposes that it can solve problems related to documentation architecture (how to organize it). Some organizations have done this quite literally, and it seems to work for them.
Gatsby is a SaaS open-source web development tool, and their users generally require some level of technical skill to use the product. Or take our cooking example – a chef would likely appreciate the ability to clearly decide if they need a full recipe or just a list of ingredients.
If the user audience already knows what they’re doing to some extent, they may know what information they need in the moment based on their existing knowledge. For a more technical audience, explicitly grouping and naming the types of content in context of the type of information that the documentation can offer makes a lot of sense.
For most of us in gen pop, however, we may not know the type of support we need; we just know our problem or question.
Someone who follows an adjusted Diátaxis framework for their team recently told me that their users get confused between document types, like reference vs explanation – and that’s exactly the problem. While we can and should think about Diátaxis as offering structure to documentation, we need to think about it less literally as an architecture*.
You might be thinking – so then how should we structure our content?
That’s a bigger question than you realize! It’s on deck for another article, but here are some quick notes:
*It certainly offers structure within individual articles, and it absolutely contributes to structured content. I’ve re-framed the way I talk about structure as a concept since I published this article, and I’m working on publishing other complimenting resources as of early 2025. Hoping to edit this article/note when those are more organized!
Inform users with taxonomies
The overall site structure of support content refers to how it’s laid out in the help center – usually where the articles live in terms of categories and sections. Ideally, your categories and sections give meaning and direction to how your users think about your product(s) or service(s). When thinking about how to approach this, my mantra is:
Structure for new users; optimize search for everyone else.
My approach with Diátaxis directly influences search optimization (more in a sec), but I can’t give you an easy answer when it comes to the actual layout of your help center. As ever, it’s going to depend on your organization, your industry, your users, etc.
Now, you might be thinking that Diátaxis already works for new users – they can just look at Tutorials, right? Maybe, but to answer with another question: does that really capture the needs of most new users exploring your support content?
Remember, our goals are to help the highest number of users complete tasks related to a product or service. If the new user doesn’t need to learn a new skill, they might benefit more from other article types or even just seeing article titles that cover different topics.
In this age of new technology, we’re far too quick to dismiss the merit (and user need) for browsing through content. That said, addressing help center structure is its own massive topic, and I can’t get into that here. Maybe I’ll publish an article on this at a later date, but in the short term, I have a few resources which might help:
When it comes to a general user audience, it’s often better to think about structure like a taxonomy.
Taxonomies basically offer a hierarchical way to describe and classify content. They’re a huge part of the Information Architecture (IA) practice, and they’re fun and complicated in and of themselves. Personally, I always struggle to figure out what is a site structure vs taxonomy… some people call site structure a taxonomy. But I like thinking about them like this Taxonomy 101 article from NNg. An actual taxonomy is more related to backend metadata, where the structure (IA structure/site map in the article) is a simpler form of a taxonomy that refers to how we structure a website for our users.
I bring up taxonomies for a few reasons:
- I genuinely believe that an IA approach to structure is key to organizing a help center, and IA is not the point of this article. If you want to take a deeper dive, taxonomies give you a solid starting point for some research!
- Some people like to think that search and AI will dictate most support experiences, but structure is still incredibly important for those exact reasons. AI tools often learn from a website’s structure as a form of metadata; the way that a piece of information is nested helps the tools decide how relevant that information is to a specific query.
- I like the way that David Kay talks about taxonomies, especially in their creation and maintenance. One of the taxonomies he identifies is structure, and it’s worth exploring his approach.
The biggest takeaway about literal layout is that it informs those consuming content, whether as metadata for machines or mental groups for humans. It’s helpful when structure focuses less on the type of documentation and more on something bespoke to your organization.
And bringing it back to Diátaxis…
I said we should look at it less literally in regard to organization. Instead, let’s look at the implications of defining clear article types.
I’ve done a lot of research on different practices in the support content space, and the topic of short, focused articles comes up CONSTANTLY. We also want to work toward mutually exclusive content, meaning that the same information isn’t repeated in a dozen different places.
These ideas – focused and mutually exclusive content – seem to have a symbiotic relationship; it’s a lot easier to do one when you’re thinking about the other. And here are just a few reasons that they matter:
Shameless plug here!
I could keep going on about mutually exclusive content… and actually I have! A reminder that I’m writing a course that includes a whole whole lesson on this, so feel free to check it out if you really want to get into the details.
And I understand that it can be hard to keep things concise – I mean… you’ve gotten this far, and I’ve had A LOT to say about this one topic (and I’m not even done!). So how do you create focused and mutually exclusive articles when topics can get so big?
Break it down into article types based on user needs!
I promise I’ll be taking a very close look at each article type before I’m done; here’s a quick link to that section if you want to skip the next bits. But first, it might help to understand why I landed on these specific article types. And that ties into how I’ve adapted the user needs.
Reinterpreting user needs
Within about a week of discovering and marinating on the idea of Diátaxis, I realized that it would be most useful for clarifying support article types.
Article types determined by purpose help to:
I was already distinguishing certain article types based on purpose; suddenly, I had a visual and actionable framework to clarify the purpose of almost any given article based on recognized user needs.
With a superficial understanding of the framework, I found that I could almost perfectly match article types that I’d already identified into one of the Diátaxis quadrants. There were two types that would always be outliers (FAQs and News were always meant to be extras), but it mostly worked.
Until it didn’t.
As I started to go deeper and better understand Diátaxis itself, I realized my mental gymnastics were forcing certain articles into the framework like a square peg in a round hole. It just wasn’t right. It became increasingly clear that the needs of documentation for a technical user are a bit different than the needs of the more general public.
Adding another layer, the writers and their experience are different too. Technical documentation naturally requires its writers to understand the specific language of the craft or skill; in software, that understanding often exclusively lives within product and tech teams.
If I was going to make this work for a less specialized population of writers, it felt important to try and over-simplify the framework. And I was consistently struggling to articulate the relationships between the user needs and each document type. Maybe it was the big words that sound similar out loud, but even attempts to break those down felt a bit muddled.
I realized that I needed to actually identify the axes of the quadrant. With some help, things started to take shape.
Starting with the map
A shout out to Lily Cutler, whose perfect questions about this framework led us to mapping out a variety of article examples and keywords onto the existing Diátaxis map. Together, we explored real examples of each article type, and things started to take shape.
Notably, the axes seemed to come down to needs within the user’s control (goals) and needs more outside their control (requirements):
User goals: Study and Action
If a user is seeking information, they generally know if they’re looking to learn about something vs looking to do something. Learning absolutely relates to the doing, and doing can contribute to learning, but you typically know if you’re capable of doing something or need to learn a few things first.
Applied to cooking: When I started exploring sourdough recipes, I wanted all of the tips and details readily available; I didn’t trust articles that made me seek outside sources to figure out whether I have a certain tool or ingredient. Alternatively, I’ve made cookies all my life, and I will seek more information if I need it; I’m not going to consult a recipe that forces me to skim through a bulk of context to find the next step.
When developing content with these goals in mind, you ease the cognitive burden of the reader. If the content meets their anticipated needs, you immediately increase the odds that they’ll continue looking to your content as an authority on the topic. (Ideal if the topic is your own product or service, right?)
User requirements: Specific and Broad
While users might know their goals for seeking information, they may not be as aware of the depth of information they require. ‘Requirement’ also loosely ties into the depth of support that a user needs.
Applied to cooking: A general overview or list of basic actions might be enough information if I’m exploring a new cooking style or reviewing the basic steps to make Charlotte (which I’ve made many times). When I’m ready to try that new cooking style or I run into a problem with activating the gelatin for the Charlotte, I’m going to need more granular information.
You want to provide the appropriate depth of information to the users who need it, but you don’t want to weigh down all of your content for the users who are more experienced or just looking around. Information overload is a very real thing (cognitive burden again!), and users might look elsewhere if the content is too dense all the time. You want to have lighter, more general resources available that link out to more detail if the user realizes they need it.
Here’s a more direct visual of this reinterpretation – I’m mostly including it because sunk cost, but I do like the quick breakdown of these needs:
Addressing business needs
When we’re addressing needs of a general user audience vs the practitioner of a skill, we do have to address some organizational needs too. Generally, the organization has developed the product or service for that general user audience, and the business does have certain needs based on available resources and overarching priorities.
To be clear, we’re still focused on documentation, where content is intended to inform users. The business needs that I’ve decided to include are pretty basic and very much user needs as well. Documentation ultimately serves the users, so we’ll continue to focus on the value behind meeting the user-specific needs.
The two business needs that I find most relevant to documentation and the people who create that documentation are:
These should be fairly self-explanatory; we don’t want to over or under invest resources in the wrong places, and we do want users to be aware of certain updates or events related to our products or services.
These business needs are implicitly prioritized throughout our framework. Frankly, the existence of a framework which encourages intentional content creation and maintenance meets a variety of business needs. However, these needs are also addressed with very specific content types: FAQs and News.
It’s possible that I’m trying to force a framework around my previously identified article types, but it seems to work well when I adapt the Diátaxis compass. I’ll get into that next, or feel free to jump ahead to my breakdown of each article type and how they function together.
Tweaking the compass
The compass more or less corresponds to the axes of the map. Between staring at my examples, the original map, and the expanded meaning of each user need, things started to click. Here’s how the Diátaxis compass looks and how I’ve re-interpreted each item. (better table/image coming soon)
Applying the new framework
With some language and visuals that feel more appropriate to my goals for support content, we can better see how the framework looks in practice. For reference, it looks something like this:
We already know that any architecture for informative content should be independent of this framework, and that applying this framework should actually simplify content organization for whatever structure you put into place.
It can also impact who owns certain types of articles. That’s the first part of this section, and then the majority of it focuses on each article type and some implications of each (in the form of ‘gray areas’).
There’s a bit of overlap in these two topics given that the actual purpose of an article can often dictate who owns it; obviously that means content ownership can be an implication of an article type. It’s impossible to separate these two things, but I still feel it was worth talking about delegation more generally on its own. So if you want to look at content delegation as its own topic, keep going sequentially! If you’d prefer to read about delegation in context of specific articles, here’s a quick link to the article breakdowns.
Delegation based on user needs
At this point, I’ve established that a broader audience means a broader business interest in that audience. If that’s true, then a framework to clarify responsibility of documentation types across teams at an organization would be pretty helpful, right?
That idea is exactly how I was introduced to Diátaxis. Quick story time!
I’m very lucky to have someone in my corner who works at a massive enterprise organization. We meet periodically to check in and talk things out, and I was thinking out loud about something (I forget what exactly, maybe content ownership), and she encouraged me to check out Diátaxis. She’s a content strategist and manages a small team focused on learning content; another manager owns their support content. As it turns out, politics are everywhere, and she started looking to Diátaxis as a way to define what documentation types her team owns (and what they don’t).
Even when I started tying the Diátaxis framework to article types, I never let go of that initial concept – the framework of distinct user needs can still absolutely tie into who creates the content. Who actually owns and develops any form of content is going to depend on your organization, however the user needs can tell you a lot.
Exploring from the lens of support content
In theory, each of the article types could live in a help center under the umbrella of support content. In order of priority to support content, we have:
If you look at the location of those articles on our map, you might notice that the two article types which address the user goals of learning are at the bottom. There are two reasons for this:
When it comes to business needs, especially user awareness and News articles, there’s also a lot of crossover. Should marketing own the promos? Should product own the release notes? All good questions, and likely answered by collaboration.
If you’re looking for specific guidance:
I’d suggest that content ownership should generally align the workflows and motivations of a particular team. Misaligned priorities are often what lead to content maintenance problems; product teams might be much more concerned with getting out the next release than updating an FAQ, and they should be. Consider the fact that Support is going to get the user feedback if a How-to or Guide is outdated, so it’s in their best interest to keep that content current. Marketing is likely the most in tune with industry updates, so they’re most likely to stay on top of Resources.
However your organization handles documentation, the goal is to move away from content landing arbitrarily with one team ‘because marketing owned it first.’ Content ownership, authorship, and location should be intentionally based on its purpose and the needs of the user.
Applying the adjusted map to article types
Or, an abridged journey of pasta making documentation.
So let’s get to the point. Why did I put myself through thinking and writing all of this? Why did I put you through reading all of this? Why does any of it matter?!
It all comes back together when we look at the article types. Ultimately, the framework can inform us on how to create intentional, focused content based on user needs. Even if a complex topic requires A LOT of information to cover it, the framework requires us to focus on purpose. If we can create intentional, focused articles based on user needs, we can keep working toward robust yet mutually exclusive content to meet those needs more holistically.
Whenever I talk about this with anyone, it’s most clearly understood when I get into article examples. So before I try to articulate how these articles can apply to your documentation practice, we’ll look at each type of article alongside the example of making pasta. And I’ll start with how I first learned how to make pasta: with a Tutorial~~~
You’re going to notice A LOT of gray areas with this framework, most of which involve the article types. While this framework is great in theory, it’s still a theory; practical applications are always going to depend on your organization, your product(s), your industry, your team, and your users (to name a few).
After each pasta example, I dive into these gray areas based on that particular article type. Some impact only that article type; some span over a few article types. In an attempt at clarity, I’ve numbered them and indicated whether they keep going with setup, continued, or wrap-up.
My gray areas mostly focus on variations in how or who or when to work with certain article types, but I would never assume they are exhaustive. Feel free to comment with any questions or other areas you identify!
Here’s a list of our article types again (with quick links!) for reference:
Tutorials
Tutorials are intended for the true beginner. They provide a safe, low-stakes environment to learn a variety of skills related to a specific task at hand.
When making pasta…
The first time I ever made pasta, my husband and I took a cooking class! We were certainly completing a task, but it was more for practice – it wasn’t the moment where we needed to make pasta for others, but a way for us to learn how to make ravioli in a hands-on environment. We were proud of the finished product, but what we really took away was a foundation for making pasta.
We learned how to mix ingredients, knead the dough, and how to know when the dough is ready to rest; we practiced rolling out the dough, then learned different ravioli shapes and filling methods; we got tips for cooking the pasta as well as what paired well with the dish.
Gray area #1 setup: Isn’t this just Diátaxis?
There are a lot of skills and steps involved in this process. And I’m not really diverting from Diátaxis itself when it comes to Tutorials. Cooking is certainly a skill, much like anything could be a skill (even a specific product or service). The needs during an introduction to a skill aren’t very different.
Does that go against everything I’ve written to this point? Maybe. Welcome to our first gray area; it won’t be the last!
The best Tutorial takes place with a student and teacher in real time. My example illustrates this point, but the challenge of documentation as a learning tool is that the learning happens asynchronously. Many online courses are the best examples of Tutorials, where learners have opportunities to apply any lessons to example scenarios.
Overcoming that requires a lot of work and skill on the part of the teacher; I would know. I’ve made this plug enough times already, but at the time of writing this post, I’m also working on a certification course about support content. I love my work in content, but writing a course has been an entirely different animal; it’s really hard! Alongside the informative content, we’re thinking about unit practices and what an exam would look like. Even the structure is super complex, deciding what information should go in what order that best supports the learner’s experience.
This is why Instructional Design exists – Tutorial creation can be really difficult and requires a certain skillset from those who do it. If you’re lucky to have a Training or L&D (Learning and Development) team at your organization, I would 1000% recommend leaning on them for any and all content that crosses into the Tutorial space. Sometimes marketing teams will also lean into Tutorials as a form of content marketing.
If you don’t have the option to delegate this type of content, I would personally put Tutorials last on the list of priorities when creating support content. Most products and services don’t have such a significant learning curve, and the resources required to create Tutorials are often not worth the effort from a support perspective. While they may be nice to have, remember that support content ultimately aims to support the ability to use a product or service. See if you can put that context into an action-oriented format, like a How-to article, instead.
How-to articles
The most straightforward article type’s purpose is in the name – how to do a specific thing. We’re not concerned with much fluff or what-if scenarios here; it should be as simple as possible, typically in a step-by-step format, to guide users through the expected functionality of a task.
When making pasta…
A how-to is most comparable to a recipe in cooking. Ingredients, or necessary context, are provided at the beginning, and then you get an ordered list of steps to complete the task. My first at-home pasta making experience was to make sheets of noodles for lasagna. I found a recipe for this, followed the steps, and found myself recalling some of the skills from our pasta class.
And there’s that first gray area again – technically I was applying skill to the directions I was following. The difference, however, is that the recipe I consulted was written with a general audience in mind. While maybe not as effective as a tutorial experience, the writer included skill-based tips into the steps. She indicated that I should knead the dough until I could stretch the ball without breakage. She included the steps for using a pasta roller in her instructions.
Gray area #1 wrap up: Is it just Diátaxis?
When we’re navigating this gray area, it’s important to know that ultimately, your content is what you make of it.
A recipe for a skilled cook would likely have skipped a lot of that detail – have you seen the technical challenges on the Great British Bake-Off? Those recipes are slim to none, and the expectation is that the bakers can apply their existing skills to fill in the blanks. I imagine a Diátaxis-inspired how-to article would be closer to a Bake-Off technical challenge, where support content might provide the recipe mommy-blog style.
Gray area #3: I thought you were supposed to break up articles if they cover a different topic or purpose?
Most of the time, yeah – you might want to separate lasagna noodle steps from pasta roller steps. Or some of that added context about how to know when the pasta dough is ready might belong in a Resource or Guide article.
But more important than following a framework is doing what’s best for your users. (And then maybe what’s best for the content long-term, never forget about maintenance hell).
If you know that over half of your users are going to need guidance around using the pasta roller, and it’s immediately relevant to that article, then it’s likely worth providing the pasta roller instructions. And if those instructions tend to vary based on the pasta anyway, it makes sense to include those steps in any of your pasta recipes instead of in one general place.
Now, if you know your users may need only the pasta roller instructions, then you may want to consider a separate How-to article about using a pasta roller. You can always link to that article in every recipe that involves the pasta roller. It might also be a good idea if those instructions are always the same and you have 100 pasta recipes. Then, if you need to update your pasta rolling guidance, you’re not looking to update that in 100 places.
Think about a resetting a password. The steps are important, but I also know that my users will benefit from seeing the password requirements in context; that’s often the real issue if someone is having trouble resetting a password (or at least it’s the biggest problem for me).
Based on the framework, I’d say the context better aligns with a Feature Guide than a How-to. But I’m pretty confident that I’d irritate more than a few people if they had to click into a Feature Guide about passwords from a How-to article titled ‘Reset your password’ (if that’s what they’re doing, that’s the article they’re going to click). I also know that it’s not worth my time to create a Feature Guide about passwords; I have so little to say about passwords outside the context of resetting them! In this situation, it makes the most sense for both me and the user if I just group any password content under a How-to article about password reset.
The above headers will open accordions with some examples. Generally, I like to ask myself if the context is good-to-know or need-to-know; is that context going to impact what the user is going to do right now?
Does your audience include users with different permissions or access to different features? Avoid the temptation to create duplicate content!
In this scenario, you’re ideally working with a CMS that can account for different user roles. That means that your CMS can recognize the role of the user viewing the content (usually via login) and will only show them content that’s relevant to them. This is how internal users might see more content than end users, or admins can see more content than a contributor.
Remember that we’re keeping maintenance in mind too. So to get even more ideal, your CMS would allow certain pieces of content within the same article to have visibility limitations; this way, the user finds the information they need with the same search queries/article titles, but you’re not maintaining multiple articles in the background.
If your CMS only accounts for user roles of entire articles, really ask yourself if an entirely new article is necessary; you might be able to get creative with notes or callouts that won’t confuse other users. Alternatively, if your user bases are extremely distinct (like Etsy shoppers vs sellers), you might be able to create similar content no problem.
As ever, do what’s best for your users (but also you!) in this situation.
I’m not going to directly highlight this again since it’s more or less omnipresent. Maybe it should live somewhere else in this article. Regarding any of your content choices though, the best thing you can do is absolutely keep the framework in mind, but focus on doing right by the actual people impacted by this content first. Remember, your content is what you make of it.
Gray area #4 setup: There are more tasks to complete this task…
When talking about making sheets of noodles for lasagna, you may have caught yourself thinking, “um… there’s more to lasagna than making the lasagna noodles?”
To that I would say, “I know, and now you’re ready for the next gray area.”
It’s not lost on me that there’s often much more to a process than one simple task. Lasagna isn’t just making the pasta – hell, most people buy the pasta and focus more on the sauces and cheeses. And some recipes might even assume you buy or have all of those, focusing on the assembly steps and bake time. We might be doing a task with at least four steps that include their own set of instructions. How in the world are we meant to deal with that?
One option is to include them all in one article – technically, the article still focuses on completing a specific task: make a lasagna. Plenty of recipes will break up ingredients and steps into sections related to each task. Another approach involves our next article type…
Guides
Guide articles can take a few different forms, but they always provide broader context for completing a task. They’re often tailored to more experienced or savvy users who prefer less information, and they’re also quite attractive to new or potential users looking to get familiar with a brand, product, or service.
When making pasta…
The thing about making pasta – if you’re making it instead of buying it, you’ve likely made it a few times. And once you’ve made it a few times, you don’t need to look at a specific recipe anymore. I wouldn’t call myself an advanced pasta maker by any stretch, but I know that I need about 100g of flour + 1 egg per serving, and then I move through the motions.
I’ve also made lasagna enough times where I know I need some kind of hearty sauce and a mixture that includes ricotta cheese (and I even prefer to make my own ricotta cheese now, it’s way easier than the pasta btw). Lasagna effectively involves at least 3 unique ingredients that someone might need direction on preparing for the final dish. But for someone a little more experienced, or even someone only starting to learn about lasagna, ALL of that information can be annoying at best. At worst, you could overwhelm to the point that they look to something or someone else for their needs.
Gray area #4 wrap up: There are more tasks to complete this task…
In recipe form, where the task is clearly one dish, it makes sense to incorporate each step into a larger how-to article. So long as the recipe clearly separates the sets of tasks in a way that’s clear to the reader (like this one), then that’s a perfectly solid approach. It’s extremely appropriate for the industry, and the structure prioritizes the goals of the cook.
And that’s the key here – you have to do what’s right for your specific industry, organization, product(s), service(s), and most importantly: your users. There’s no real right answer.
For many products and services, we know that tasks with many layers can get really complicated to absorb in one huge place. The granular details all together can also really irritate users who don’t require such specific direction. If you have decided to break up your longer content and you want to keep high-level information available to your users, then Guides become extremely useful.
Something to consider: Most Guides don’t exist as an independent article. You should always prioritize how-to content, and the decision to break up how-to articles should depend on what users are going to search for. There are all kinds of benefits to keeping focused, short articles (we touched on a few of these above).
But ultimately – support content should serve the user. If the longer article feels right (and genuinely feels like the right thing, not just the easy thing), then go for it! But if your gut is telling you that it’s too much, you might want to consider creating a Guide to compliment.
So if we didn’t want to include all of these steps and instructions in one large article, we could use a Guide almost like a home base for all the little tasks that make up the broader task. A Guide gives just enough information, including links to where the user can find more detail. But Guides might not always be best presented as steps, so let’s break this up a bit for our next gray area.
Gray area #5: Guides can take a few different forms
Guides and Resources generally take whatever form they need to take; they’re not predictable in structure like a How-to because ‘broad’ can really mean anything. That said, I’ve noticed a few patterns:
**May expand on this later, but examples would make this VERY long – consider this set up and wrapped up for now! Details will absolutely be in my course, or I’ll link to other resources as they are created!**
Gray area #6 setup: What makes this a Guide vs a Resource?
If the information in an article isn’t necessarily actionable in itself, you could certainly make the case that it should be considered a Resource. If it’s not an action, then it’s learning, right?
Now you know I can’t give you a direct answer in a gray area! It’s going to depend – and my distinction usually relies on whether the information presented could inform an action in the near future or not. I can’t do anything with an expiration date RIGHT NOW, but it’ll absolutely influence when I do something with that product. Conversely, if I want to understand why the product is going to expire because of how certain ingredients react to each other or their environment over time… now that’s a much bigger topic that could influence my actions, but it’s likely just something good to know vs need to know. Let’s get into Resources before I go in another circle here!
Resources
Resources help provide a broader understanding, or broader context, around any given topic related to your product or service. These articles are usually bigger than your product or organization, and while the details can be very helpful for users, they generally don’t provide information that is directly actionable OR directly related to your product. These articles mostly meet the needs of your curious or experienced users who want to make more informed decisions about using your product.
When making pasta…
I might find myself interested in how a certain type of pasta came to be, or why it’s used with certain recipes. Or maybe I want to know the best types of tools or materials to use when making my pasta.
Take a look at this article about farfalle, or bowtie pasta. It gives some history and tells me how farfalle is made, which includes detail about what makes it durable. The article also lets me know that it’s ideal for carrying sauces and small mix-ins, among other things. It was a fun article for me to read, and helps me understand why I might want to create that shape the next time I make pasta. It also lets me know that if I want to make farfalle, I may need durum flour, which I don’t normally keep around.
Gray area #6 wrap up: What makes this a Guide vs a Resource?
If you didn’t open the linked article, all good! But FYI, it’s a piece of marketing copy from DeLallo, who sells Authentic Italian Foods. It’s definitely not a perfect example, and we’ll get into the marketing gray area next.
This article certainly blends certain elements of a Guide, like some fast facts up top that are handy to set expectations on cooking times, and you can find lots of links to specific recipes or products. Based on my current pasta knowledge, I could probably even make a solid attempt at farfalle from scratch with the information provided.
Ultimately though, I’m not going to use any of this information in the near future. I don’t think DeLallo expects me to use this article for any action either.* Once again, your content is what you make of it.
This article part of a “Spotlight Series” to inform customers about their product offerings; they know I’m going to look at the box for instructions when it actually comes time to cook. We both know that I’m looking at this article for fun facts; any information in this article is good to know, but it’s not need-to-know when it comes to actually making farfalle.
*Unless it’s buying their farfalle pasta, which is not the same as using it. I think it’s time to get into the marketing stuff now!
Gray area #7 setup: When is it support content instead of content marketing?
This example from DeLallo is absolutely content marketing, there’s no getting around it. It contains some informative content, but it’s ultimately a persuasive piece intended to convince me to purchase their products. I think it does a solid job of this. As prospects, we tend to appreciate a brand’s authority and trustworthiness within their industry; the increasing adoption of Hubspot’s flywheel seems to prove that.
So when content marketing starts to blend with educating active users, how do you make sure you stay in the right lane? And how do you also avoid duplicating work that one team or another might be doing?
To keep it simple, content intended for prospects should live within a marketing website; content intended for active users should live within a support site, like a help center. When it’s not so simple and both audiences can benefit from the same information, marketing and support would ideally work together on these things!
Often, marketing copy will keep their content very broad about the industry or general product and end with a sales pitch. I’ve found the most success and clarity with support Resources when they consistently focus on how that general industry information applies to their specific product or service, linking over to the marketing site for more information.
Here’s a real example to better show this in practice:
When I was working with EVgo, I learned about the massive gaps in education for many EV drivers. Many dealerships sell the EV and hand over the keys like it’s a normal car, but owning an EV is a very different experience, especially if the driver intends to use public fast chargers. Their marketing team had created a really great EV101 ‘course’ to help drivers better understand charging their EV. But the EV101 resource lives on the marketing site, and we wanted to consolidate the support content that active users would need into one place. Enter Resource articles.
We’ve only created a few of these because ultimately, their marketing team has done a great job. We only wanted to put energy into Resources that would directly impact active users, like this article on types of EVs or this article about EV charging speed. Each of them address high-volume topics for the support team, refer back to existing marketing content, and ultimately focus on information useful to active users. These topics aren’t necessarily about using an EVgo charger or account, however they do provide context that eases the user experience with EV charging, easing their experience with EVgo by extension.
As we move along these article types, it’s easier to focus on a specific product, especially since our last two article types look into those crossover business/user goals. We’ll get back into pasta though, the EV stuff can be a lot! We’ll keep going with DeLallo because I like their bowtie article, but let’s pretend that I buy my pasta flour from them. So I’m still going with the goal of making pasta here, and DeLallo provides a product which allows me to achieve that goal. Here we go!
FAQs
FAQs as we most often see them suck… like, a lot. Yet they may never go away. Leadership loves them, some users like them, and they can actually be incredibly useful when approached with intention.
When done well, they don’t require a ton of effort to create or maintain. I like to think of them as a dynamic complement to a help center’s core articles (a myriad of the first 4 types we’ve covered). They’re great for temporary information and testing new content topics; also, if there’s a legitimate frequent question* that your core articles can’t capture, then it might be worth adding those too.
*I’m aware that my interpretation of FAQs are hardly “Frequently Asked Questions” – in practice, I actually call FAQ sections something like “Login questions” or “common questions” to avoid misleading users. However, because these all exist in a question format and FAQs are such a dominant feature in business, I still refer to them as FAQs. Sometimes it’s easier to change perceptions about a thing that already exists vs introduce another new idea altogether!
When making pasta…
If I’ve purchased my pasta flour from DeLallo, I may have questions about shipping. In an ideal help center, they would have articles that cover a lot of this – How-to check the shipping status or How-to see my shipping address; maybe there’s a Feature Guide related to shipping expectations or a Troubleshooting Guide for delayed or damaged orders; maybe a Resource explaining how they ship the flour and why. Those articles would cover a lot, but one true fact about anything in life: What works for most will NEVER work for every single person all of the time.
DeLallo actually does have some FAQs on their site – I won’t get into the page itself (yet), but there are a few examples of a solid FAQ:
- What if I need to change my order after it’s placed? If the support team starts to see an influx in requests to change their shipping options after an order is placed, and the answer is always the same, maybe it’s worth creating an FAQ before creating or editing a larger article.
- Why am I forced to pay Priority shipping? While this could be covered in a shipping guide or a guide about perishable items, customers searching with these exact terms may not clearly surface those articles. This one sounds like a valid FAQ worth including (and the answer would link to the articles with more details!)
- I don’t see anything seasonally in September, but I imagine that holidays will impact normal shipping; instead of working that into an existing article, it could be worth highlighting in its own article that’s easy to publish and archive as required.
Gray area #7 continued: When is it support content instead of content marketing?
FAQs are often a starting point for support content, where someone with the best of intentions began documenting common user questions. Sometimes they are helpful, but most of the time they accumulate into an information seeker’s worst nightmare.
Another FAQ trend: they normally start out on the marketing site. And it makes sense. When organizations, especially young ones, are low on headcount, the marketing team likely contains the only content writers AND they have easy access to a publishing space. The quality of those FAQs then becomes completely reliant on how much support exposure the marketing person might have as well as their bandwidth to prioritize that content.
Transition of that support content can get a little weird though. Even if the content is clearly intended to support active users, marketing teams often get traffic to FAQ pages, prospects may find them helpful, and content is often something that people hold personally, even if they didn’t create it. You’ll want to clarify the content purpose, ask yourself if it’s worth making a change, and then maybe look into my article on networking with your coworkers because conversations are usually the best way forward. Ideally, you’ll land on a compromise that serves both users and internal parties well (because topics like the return policy are in fact valuable in both places; I know I’d be looking for that info before and possibly after I buy something.)
Gray area #8: Aren’t all FAQs bad?
A lot of very important content strategists are very adamant about no FAQs. You can actually find guidance on them from governments (UK: FAQs: why we don’t have them; US: Don’t use FAQs; Canada: Avoiding FAQs, with one exception).
Most of the time, I fully agree with their points. I tried to get on that bandwagon. I was also constantly asked to create FAQs by people who don’t like to hear the reasons; I also found myself struggling to put random pieces of information into the ‘right’ places at times. Eventually, I accepted my fate: FAQs are here to stay (at least in support content).
I like to pretend that I started seeing the business needs of FAQs from the beginning; after all, leadership kept asking for them! But really, it all started out of necessity. While working on one of my projects, there was a weird, temporary login bug that was impacting new users. We wanted to incorporate it into the help center, but it wasn’t fitting nicely into the login How-to article, and we didn’t really want to call attention to the bug in the first place. We also didn’t know when Product would be able to release a fix, and there was no maintenance plan that early in the project (I like to very literally start projects from the beginning).
Enter the FAQ – we could provide the workaround for the temporary bug and link to the core How-to article for further support. The How-to article would also link to a landing page for any relevant FAQs. When the bug was fixed, we could simply archive the FAQ article, no further action needed.
I started looking for other specific instances where those flexible articles could come in handy:
There’s a lot more to handling each of these, but I’ll make another plug for my course here in the interest of moving on. At minimum, remember; so long as you approach FAQs with clear intentions, don’t let ‘best practices’ prevent you from meeting the needs of your users.
Gray area #9: How the hell do you present FAQs?
I’m referring to FAQs as an article type, and that really is the ideal way to create them when thinking about bots and search discoverability. If your CMS or publishing platform allows multiple layers of organizing your articles, I would recommend creating a section or landing page that is specific to topics which align with your broader help center structure (sitemap, taxonomy, whatever you want to call it). By having a ‘home base’ for FAQ categories, you can easily link any article to that page without needing to edit those links if an FAQ is created or archived. We did this for EVgo using sub-sections in Zendesk.
If you’re limited to only a few layers of organization, then do everything you can to make the FAQs as navigable as possible. Maybe DeLallo only has access to the one page for their FAQs, but to me, they’re still doing a lot of things wrong. In the very least, they could group the FAQs into topics on that single page; Liquid Death has done this, but it’s still overwhelming. If you have a lot of FAQs, it’s likely worth fighting for at least a landing page where you can break FAQ pages into categories. We did this with Envoy Global, and provided anchor links and section links to make the pages as navigable as possible.
Some help centers include FAQs at the bottom of each topic page, like at the bottom of a How-to. If that works for your users and organization, then there’s nothing wrong with it. I do caution you, though – FAQs at the bottom of a page are hard to find through search, and they can open up gray areas like I’m doing in this article. My ‘FAQ’ gray areas blend into each other, and it’s hard to decide where to place them. I may have done better to link to a separate post with everything together! (Feel free to share your thoughts with me if you’ve gotten this far!)
News
I have no nice transition for this one other than it’s the last one! We’re keeping people aware!
This is another marketing crossover, but if your active users are not subscribed to marketing emails, or those emails land in a Promotions folder, users may not see updates about certain promotions or seasonal information. And I know I never read the generic app updates anymore, so new features are often a surprise.
If these updates are not always obvious to users, they may have questions when they see them. Better yet, they may come to trust the help center to provide those updates anyway (users will trust a good help center to keep them informed, after all). News articles are intended to provide basic information about those updates – why it happened, if and how it impacts users, and often linking to other articles for more detailed information.
When making pasta…
In the case of DeLallo, maybe I’ve been using their semolina flour for most of my pasta. I saw a seasonal promotion on flour not long ago, but I accidentally deleted the email. If I have questions or want to learn more, the help center is a great way to find that information (and more) without needing to contact anyone and wait for a reply.
As another example, I know DeLallo doesn’t sell durum flour, which I need for my farfalle recipe. If I’m already in the habit of ordering just the semolina, I probably stopped looking for durum flour a while ago. I get their marketing emails for seasonal promotions, but I don’t often look for those mid-year and they don’t normally talk about new products.
As an active user, I do tend to poke around their imaginary help center at times. If there’s a ‘What’s new’ category that includes updates on new products (kinda like release notes talking about new features…), I might just decide to follow that topic for updates; I can trust that support content will provide updates more closely related to my needs, even if it’s just a simple list of new products (kinda like bug fixes).
(Can you tell that I’m trying to draw a new product/product update comparison here? It got weird, so to be clear: Sometimes release notes are complex or minimal or hard to find, and marketing doesn’t need to invest in every small update. The help center can be a great middle ground for the small things that may not impact the organization so much, but make a huge difference to some users.)
Gray area #7 wrap up: When is it support content instead of content marketing (or product marketing)?
In theory, marketing should own any content related to promos and updates; often, the purpose is to drum up more business, and it never hurts for prospects to see how an organization is growing to meet their user’s needs.
Users don’t see your org charts and who should own what, however. If they have questions, they turn to support. This is another example of how important internal, “cross-functional” communication is to content efforts. If customers are going to have questions and contact support, then some form of support content should exist. Maybe it’s the News article alone, or maybe that News article will link to other relevant content that feels necessary.
Another truth of content in general: It’s ALWAYS going to depend on your organization, your industry, your product, and your users. So long as you have the user needs (and best interests) in mind, most teams will want to help make things work. Ultimately, you’re all on the same team!
Gray area #10: Shouldn’t new features and updates be worked into the existing ‘core content’ articles?
Once again, it depends!
If an update is permanent, like a new or changed feature, absolutely ensure that any existing content is still accurate to support the user’s experience.
After that, it’s really up to you on how to handle those updates. News articles don’t really have a specific structure, other than making them look approachable. They can flex based on the specific update, what other teams are creating for that update, and how much you want or need to invest in the content surrounding that update.
Here’s how I would handle a few examples:
Once again – do what’s right for you and your users, talk with your coworkers, and things will usually turn out pretty well!
That was a lot. I may shorten a significant portion of this later. But something that kept popping into my mind as I worked on this (for way too long): Diátaxis has an entire website dedicated to it. This framework probably warrants at least a few pages to break it up… but as Mark Twain (or maybe Blaise Pascal) once said, “I would have written a shorter letter, but I did not have the time.”
So maybe later, maybe not. This was a fun little free-write break. Let’s wrap this up!
Final thoughts (for now)
At this point, we’ve more or less seen the article types in action. I hope that it makes sense by way of pasta, as many things tend to make more sense when pasta is present. Maybe. Again, this has been a lot for me too.
So instead of an English-teacher-approved conclusion that would make this even longer (there’s a TL;DR up top that’s close enough), I want to end with the idea of naming this thing. The more I’ve explored my own interpretation of the Diátaxis theory, the more I’m convinced that it can stand on its own.
In the early stages of creating this article (which was so long ago, I’m fully ashamed of how long I’ve spent on this), I was procrastinating by playing with the idea of naming it. Given the origin of the term Diátaxis, I of course started looking into Latin/Greek prefixes. I’d gotten as far as distinguishing that my interpretation lies in a broader, more general audience. I started to like the ring of pan-diataxis to imply it’s for all users, not just those with a more technical skillset.
I never came up with any better ideas, so if you made it this far and support the idea of naming it, please feel free to send me your thoughts and suggestions! I’ve never been so relieved to end an article.
Maring Eberlein
Some might call me a little obsessed with support content, and yeah… I’ve definitely found my niche somewhere between the support and content worlds. While growing within my first role in tech as a support agent, I saw the impacts of clear communication for users first-hand. I also experienced the challenges that come with a lack of resources for an undervalued craft. With a lot of luck and good people in my corner, I’ve been able to focus my work on my interests with the larger goal of supporting the supporters. I know you’re out there, and I hope this was helpful! Please contact me with any suggestions or requests!
