Hi, everyone. We're talking about the Diataxis documentation framework today. The reason is that I just joined a startup and I've been doing documentation. And when I first joined, I had no idea what I should actually start working on first to make it flow better, Bearing in mind, the documentation hadn't really had a lot of love put into it yet. So it was difficult.

But then I remembered Matt from Replit had told me about the Dear Taxis documentation framework and genuinely really helped. I feel like the structure is way better for our documentation now and it's just so much clearer to me about where things should go, what kind of content should exist. So we're diving deep into it in this episode. Enjoy.

If you're sitting there, you know, thinking about how do I write docs for my product? Or maybe you're writing docs yourself or you're a developer, this is a great framework to think about how to divide up documentation, how to organize it in a way that's useful but also discoverable and navigable for your users. A It's really good way to be able to kind of go out there and show people that you care, to prove that you can create high quality experiences for developers.

So in this episode, I wanted to dig into what is Dear Taxis and look at what people have been saying about Dear Taxis, kind of talk through some of the hacker news threads, look at some examples of a company that has been using Dear Taxis, and then also talk about my experience in the first week of trying to implement Dear Taxis and some of the things that I've learned. I hope this will be interesting to you. Please let me know because you know, I will still carry on to do a lot of the interview formats. But you know, like I I just want to solve my own problem here and I want to learn about Dear Taxis. And so I wanted to do an episode that I hope will be helpful to you guys as well.

That's how I think about scanning DevTools by the way, is what is useful to me and that's why I'm trying as well to put myself more into the position. Okay. So let's take a look at what is Dear Taxis. So Dear Taxis markets itself well, I should say markets. It's a free project.

The founder of Dear Taxis is Dan Daniele Prosida. He's a core developer on Django, of course. Anyway, so Dan Daniele, awesome guy clearly. And he has written a systematic approach to technical documentation offering. Okay.

So let's get into it. Dear Taxis is says that there's like four types of content in your docs. There are tutorials, how to guides, explanation, reference. K. I'm gonna start with the easiest one.

Reference is the stuff that yeah. I mean, you already know what that is. That's like the, you know, if you go like your API reference docs, your SDK references, it's just saying exactly how it is. Right? There's explanations also quite straightforward where it's like, if you've got so I'm I'm working at layer code and if we want to explain how do voice AI pipelines work in general.

And like what are the things that could matter and it's not really a specific it's not solving a specific problem but more just helping you learn. Those ones are easy. Right? These are the two that get people tripped up. There's tutorials and then there's how to guides.

And honestly, I kind of thought that was the same thing. If I heard tutorial, I think that's a how to. What's the difference? So I'll let Daniele explain the difference between the two as well as how each quadrant relates to each other.

Now, a tutorial is a lesson. A lesson that takes the reader by the hand through a series of practical steps to realize a project or complete a meaningful exercise. The only way one learns a new skill is by doing. Tutorials are learning oriented. Your task in creating a tutorial is to create a learning experience.

One in which the pupil learns by doing things under your direction. Your tutorial must be repeatable, must instill confidence, must result in success every time for every learner. It must be concrete and particular. Next, how to guides. A how to guide takes the reader through the steps required to complete a specific task.

How to guides are recipes. How to guides are task oriented or or problem oriented. It serves not the beginner, but the already competent user. It responds to a question, how do I do such and such with a series of actions and only actions without digressions or explanations or attempts to teach. Tutorials and how to guides are similar because they're both concerned with describing practical steps.

How to guides and reference share with each other that they both serve our work. They they are what we need when we're actually working. Reference and explanation are similar because they're both concerned with theoretical knowledge. Explanations and tutorials have an affinity because both serve our study of the subject.

So let's go swiftly onwards to reference. Reference guides contain the technical description, facts that a user needs in order to do things correctly. It's facts basically in this in the references. Okay. So like a how to guide, reference documentation serves the user who is at work and it's up to the user to be sufficiently competent to interpret and use it correctly.

So don't mix facts with like your sales pitch or your explanation of the big world of your dev tool. You just tell them, do this, do this, do this. Because they're there to do work and they're using it as a reference. K. So then we have explanation.

So explanation, explanatory guides provide context and background. They serve the need to understand and put things in a big picture. Explanation joins things together and helps answer the question, why?

Scaling DevTools is sponsored by WorkOS. WorkOS helps you get enterprise ready. That means they give you all the things that you need to start working with enterprises. Things like audit trails, GIM provisioning, role based access control, and single sign on. Let's hear from Utpal from digger.dev, a

dev tool using WorkOS. We haven't had to think about Odd at all. I think support is great. We have a Slack connect channel with them. Issues, if any, there haven't been many, but anytime there have been issues, it's been addressed super quickly.

So odd trail, SSO, stuff like that, we don't think about that anymore. Generally, we don't think about that anymore. And you don't necessarily think about these enterprise features, but they still lead revenue, and it kinda is a no brainer in that sense.

WorkOS helps your dev tools start selling to enterprises much faster, and they're trusted by dev tools like Cursor, Fowl, and Vercel. If you use their user management auth, you can get your first million monthly active users completely free.

Explanation often needs to circle around its subject and approach it from different directions. It can contain opinions and take perspectives. So Work OS might explain why the biggest reason that startups fail is because they fail to cross the enterprise chasm because they don't have enterprise features and why this is important and why big companies care about role based access control. And all these things that me as someone that's never worked for a big company, I don't know why they care about that. That's that's new to me.

And and also, Black OS have this opinion that they believe the big reason startups fail is because of not crossing the enterprise chasm, but someone else might disagree. So that would have no place in the in the references. Right? But as an explanation, it's interesting. And it could still help you understand their products more.

So let's have a look at an example of someone who did a really good job with documentation called Sequin. Again, I'm gonna talk this through. This is better on video if you do have it. Spotify has it on video, YouTube. But I'm gonna talk for it as well.

So hopefully it's still good, over audio. So I'm on this website called Sequin and I found them on Hacker News and they said, this was, eight months ago. We just applied this framework to the Sequin docs two weeks ago. It has felt so nice to have a framework. I think our docs flow really well now and it's been easier for us to add and maintain docs because we know where to put things.

Oh my god. A 100% by the way. That was like that was my biggest takeaway from Dear Taxis. The slightly ironic part is the Dear Taxis dogs themselves are a bit obtuse. Daniella, Sorry.

It's a little verbose. So it took a couple passes for it all to click. The analogy I give my team that was helpful for everyone's understanding. Imagine you're shopping for a piece of cooking equipment like a pressure cooker. The first thing you're going to look at is the quick start, the tutorial.

How does this thing work generally? You just want to see it go from a to b. Then you're going to wonder how to use it to cook a particular dish that you like. That's a how to. If you're really curious about anything you've seen so far, then you'll flip to the reference to read more about it.

For example, you might check the exact minutes needed for different types of beans. See, I actually think that you might do that if you start to go off piste and start to do. I don't really I I kind of want to like follow this how to but maybe I wanna do something extra. How how am I do that? Rather than just as an interest but that's my only like nitpick here with how I would interpret it but I could be wrong here.

Anyway, and finally, when you're really invested in pressure cooking, you want to understand the science behind it, why pressure affects cooking times, how the safety mechanisms work, etcetera. That's when you read the explanatory content. Comically, our docs were completely backwards. We lead with explanation. How sequin works.

I think that's the natural impulse of an engineer. Let me tell you how this thing works and why we built it this way so you can develop a mental model, then you'll surely get it. Right? While that may be technically accurate, a person doesn't have the time or patience for that. You need to ramp them into your world.

The quick start, then the how to, then the reference flow is a great way to do that. Then if you really have their attention, you can galvanize them about your approach with explanatory material. Okay. So then let's take a look. So how Sequin have structured things is on the left hand panel, they have a section called getting started.

And they they they have what is Sequin? Interestingly. But then they also do have quick starts. And they have running Sequin, connect Postgres, set up CDC sync. I should say what Sequin is by way just because we're going inside docs.

Discover how to use Sequin to build real time Postgres, change data, capture pipelines, which sounds very useful. So they have a get started section where they have quick starts and they have quick starts for different, I guess, streams of data that you're gonna get. So like Redis and TypeSense and Kafka. And then they they have like a kind of nice little quick start on how to do that. So all of these are top is like seems to very much be like tutorials like getting started tutorials.

And then they've got sequin managed. So it seems to be interesting stuff. I don't really know how that fits in. I guess this is maybe more of a explainer on what they do and how they how they run on AWS. It's kind of like a product almost explaining what they what they offer.

And then below that they have setup guides. So AWS Kinesis, how to stream Postgres to AWS Kinesis. Okay. No. They have a they have a section called how to, guys.

This is easier. So they have how to deploy to production. So that must have also previously been a tutorial. But they have one how to deploy to production, learn how to use sequence CLI for version controlled consistent deployments across environments, test with sequence, create audit logs with sequence, annotate changes, we'll see how to annotate database changes. Okay.

So then much more to the point. Alright. So Dear Taxis. Let's go back and just do like a kind of another map of how Dear Taxis works. So if the content informs action and serves the user's acquisition of a skill, then it must belong to a tutorial.

They have four of these by the way. So that that's the first one. Then we have if the content informs action, so just like a tutorial, and serves the user's acquisition application of a skill, not acquisition of a skill, application of its skill, then it must belong to a how to guide. If the content informs cognition and serves the user's application of a skill, similarly application of a skill, then it belongs to reference. If the content informs cognition and serves the user's acquisition of skill, like a tutorial, not like a how to guide or a reference, then it must belong to explanation.

So one of the things that I found was like useful about ataxes is they say like, don't try to just implement it altogether. So they say there's this very simple workflow for the ataxes. Consider what you see in the documentation in front of you right now, which might be literally nothing if you haven't started yet. Ask, is there any way in which it could be improved? Decide on one thing you could do right now, however small that would improve it.

And do that thing and then repeat. That's it. Do what you like. You can do what you like with dear taxes. You don't have to believe in it and there is no exam.

It is wholly pragmatic approach. I think it's true, but what matters is that it actually helps people better create better documentation. If you find that one idea or insight in it in that seems to be worthwhile, help yourself to that. There is an extensively elaborated theory around Dear Taxis, you don't need to subscribe to it or even read about it. Dear Taxis doesn't require a commitment to pursue it to a final end.

You can just do one thing right now and even if you do nothing else ever after, you will at least have made that one improvement. In practice, what you'll find is that each thing you do will give you a clue as to the next thing you do. You only need to keep doing them. At this point, you have read everything you need to do to get started with Dear Taxis. You can read more if you want and eventually you probably should.

But you will get the most value from the guidance in this website when you turn to it with a problem or a question than when it that's when it comes alive. Yeah. So I started to try to do this. So if I go to like docs.layercode.com this week, these are very much work in progress. And I just decided to like totally lift the columns to be exactly what this hacksure says.

So I have one section on the left that's got start here and it's just getting started. Because I think I want to have like one place where people come and you know, not and eventually it'll get more complicated, I want them to look. This is the first time they're looking at it to look here. And I want there to be a very very quick way to do it. Right now, there's a pretty long tutorial that I wanna cut down.

And I want it to just be a CLI command that you just get started and then you see how it works. So this is this will be like a tutorial, a quick start. But then I go straight to the attacks and stuff. So I have four more columns. So I have a star here, the first one, and then four more.

Tutorials, how to guides, reference, and I guess it should references, it should be probably. And explanations. I only did it this week. And so tutorials have got stuff like get started with Next. Js, get started with Hono, get started with FastAPI.

And I actually didn't write any of these. I just renamed them and moved them. And luckily, our dogs aren't our dogs aren't really indexed by Google yet. So I could just move all these things without worrying too much about redirects and everything. And then I have how to guides.

So right now I haven't got that many. We've got integrating layer code with Twilio and it's very, short. And it just says this guide walks you through, which you probably don't even need to go, but it's just stuff like go to layer code dashboard, open the client settings, enable Twilio phone calls and then save changes. Go to layer code. I'm free.

Go to layer code settings. Add the Twilio SID and off token and save. And yeah. So it's like very much like we have some other stuff like deployments, create a tunnel for webhooks. And we have and then we have reference.

We have API reference, SDKs reference, and explanations, which is stuff like how their code works. And I want like turn taking, how turn taking works in voice AI, that sort of stuff. Yeah. Before it was just like we had like a section on like front end, back end, telephony, stuff like that. It was just like, I think this is a little bit clearer.

Quite I quite like it so far. Yeah. So that's that's what I've been doing. So I don't think Dear Taxis is like a panacea. So I want to also like just throw some kind of like what people are saying.

So I was just gonna go through some Hakamese comments to give you bit of extra feedback on it. Okay. Someone else said, I'm a technical writer. Dear Taxis is similar to Dieter. On the other hand, systems like this might miss out on what users actually need.

Dear Taxis might work for a long time if technical documentation is only used in a documentation platform. However, if the same information could and should be used in more than one place, for example, in the UI, in a documentation portal, and in a mobile app, there might be need to break up information into smaller pieces in order to assemble them in different ways. This is known as content reuse, the practice of using the same content in multiple places. If there's resources and time, I always recommend to do UX research at the very start of a project so that one doesn't feel later choked by several severely restricted information model. And then some people are disagreeing that it's similar to Dieter, blah blah blah.

And someone else says, very popular in tech writing circles and pretty standard now as others have suggested. We do see people try to take it too far though and have literally only these four categories on their docs pages, which never works well in my opinion. It's mainly useful for a writer to keep in mind stuff like it's it's a guide, so focus on getting a result, not teaching. So and then someone else was like, only for many projects having a medium quality version of just one of those would have been an improvement. So, you know, there's lots of hackneyed arguments there.

Okay. Someone says, Dear Taxis is a great way to structure documentation, but I think its real value is in simplifying how we think about writing docs. It shifts the focus from trying to cram everything into one perfect document to recognizing that different users have different needs. Like tutorials are for learning by doing. Guides are for solving specific problems.

References for quick lookups. An explanation is dive into the why. That clarity alone can make one write useful docs. That being said, sticking too rigidly to any system clear trap. I actually realized this comment.

I think this is like the maybe that's the best way to explain it. Like, tutorials are for learning by doing, guides are for solving specific problems, references for quick lookups, and explanations diving to the why. It shifts the focus from trying to cram everything into the one perfect document recognizing that different users have different needs. Love it. I think that's a great way to actually explain it.

I read this and I think this might have been the one that made it click for me. Okay. Someone else is saying like, they like the idea of it and they've met Daniele at PyCon UK. He's talented, very friendly chap. But they have reservations about this being about being this rigid, about the differentiating between the various areas of documentation in this way.

During a sprint, I was told that the docs I was preparing, not by Danny LA for the record, were mixing modalities and not acceptable because of this. Not pulling rank, but I've been a teacher for twenty plus years and I have a responsible, reasonable idea of how to explain things and how to scaffold learning. But they say as long as there's not total rigidity, then this is a great tool for deciding how to produce documentation. Yeah. So I mean, I'm a big fan of DirTaxis and I'm using it to build documentation for Logd.

I'm curious how people see it and whether it's useful to build documentation. Okay. Let's have a good look at Logd. Oh, they've got I recognize Dear Taxis. They've got introduction.

They've got tutorial and they've got explanation and they've got reference. Where is how to guides? Where are the how to guides? Log d. So, you know, but everyone's got at the top what is Log d.

Is that the first one you get to? Quick start. See, I think this is better than what Sequin had even though I think this is great. But I think you should I feel like they told they said that the quick starting with the quick start is the way to go. But they start with how what is Logd.

So I'm very curious to hear if they changed their mind. Anyway, what Logd is web based platforms help monitor, track, and analyze application logs in a real time in real time locally. So I have tutorials, Docker logs. I know. I know what's going on here.

Docker logs, web UI. Okay. Let's go. Okay. I don't like the way that this appears.

Anyway, the sidebar disappears when when I click on it. So I have explanation, following logs, command modes, loading logs, traces, traces visualization. Okay. So anyway, check out LogDay. I'm gonna put a link in there as well.

But they seem to like it. Okay. So I think that's all I'm gonna cover here. I have actually invited some the guy from Sequin onto the show. Let's see if he comes on.

Log D as well if you're up for it Or anyone else that's introduced Dear Taxis and has strong opinions. Love to talk to you about how you've done your documentation. I hope this is helpful. Please let me know. I do want scaling DevTools to be useful.

It's not really entertainment. It is like something that I hope will help you build a better DevTool and I hope will help me build better DevTools as well. So let me know and see you soon. Also, Matt from Replit shared a ton of good interesting ideas around creating educational content that really works for developers. So if you haven't listened to the episode I did with him, go check it out.