Organising content with the diátaxis framework
November 2023
Organising information is crucial for improving user experience. Information that is well-organized reduces user frustration, minimizes the time and effort required to locate specific details, and ultimately promotes engagement.
The problem is that there is an infinite number of ways to organize content. When there are so many degrees of freedom, the most likely result is chaos.
This article offers insights into one specific way to think about content and its structure. It discusses the benefits of tags, and categories to guide users through information more effectively. By exploring this approach, I hope you can gain a better understanding of how to tackle the challenges of content organization.
With that in mind, let’s get on with it!
Diátaxis
If you haven’t read about the diátaxis approach to technical documentation, check it out because it is very interesting. There is lots to it but, for this article, the main focus is going to be on the map of needs.
The diátaxis map
The map is a two by two grid. The horizontal axis is divided in Serve our study and Serve our work, while they vertical axis is divided in Practical steps and Theoretical knowledge.
This is helpful because, right from the start, you can focus on what you want to offer. For a personal site, I think it makes sense on the left part, the Serve our study part. When you are writing a personal blog, articles are mostly for sharing your knowledge with others. This sounds a lot like Serve our study.
Additionally, you can choose to work on the right hand side, the Serve our work, from time to time, but it is clearly not the main priority.
As an example, this article is an Explanation. It focuses on Service your study, while talking about theoretical knowledge. You can use it to apply this knowledge practically later, but the main goal is to explain a concept.
Once you understand the different quadrants, you can gain a lot of clarity for your publications. For example, if you are writing an explanation article (like this article), it can be counterproductive to mix it with a tutorial on how to implement categorisation in a Jekyll personal site (which I was doing before thinking deeply on the diátaxis framework).
If you want a good explanation on why it can be counterproductive to mix quadrants in the same article, please read the diátaxis site (The Collapse of the structure section in particular) because it is enlightening. The next section does not explain this, but it touches on another diátaxis idea, the Needs.
The diátaxis needs explanation
The user whose needs Diátaxis serves is the practitioner in a domain of skill. A domain of skill is defined by a craft - the use of a tool or product is a craft. So is an entire discipline or profession. Using a programming language is a craft, as is flying a particular aircraft, or even being a pilot in general.
This is amazing! It gives you a great way to think, for example, on the categories for your personal site. What are you going to talk about? Well, start by thinking on skills, tools, a programming language, a framework. Whatever it is that you think is your craft.
It sounds a look like a good way to think about categorization for your site.
Categories
In a categorization system, content is typically placed in one primary category, which means it can only belong to a single category at a time. Coming up with the set of categories you want to apply to your content is not an easy task, but with the help of diátaxis, you can think about it as the crafts you want to talk about.
If you are selling products, use the products:
If you are an online course site, use the course topics:
If you are a news corporation, use the news topics
If you are a personal site, talk about your crafts (the knowledge you want to share with your visitors):
So, if you are the owner of a personal site, use your craft. But, what is your craft? That’s something you need to think about. For me, I’ve decided to start slow and grow organically. Because of the type of articles published already in this site, the two main crafts at the moment of writing this article are: Writing and Software development (This last category contains a subcategory for Jekyll, since this site is built on Jekyll).
Tags
Now that you have the main categorization for your site, you need a way for visitors to be able to explore your site in a less restrictive way. For that, you can use tags. The content that you publish defines the tags, and they’re tangential to the category. The tag set is more dynamic, and it happens organically with each piece of content. Tags allow the visitor to explore the site in a different and less organized way.
That’s all!