On today's episode, our hosts Sarah and Bryan are chatting about Documentation with Adam Wathan from Tailwind CSS. To talk about this today, we invited (for the second time in the show) Adam Wathan, creator of Tailwind CSS. Tailwind is a CSS framework optimized for building custom designs really quickly without having to start totally from scratch.
Documentation is a tremendous topic, especially in tech. We often joke that "people don't read the docs". But when documentation is judged insufficient by the community, you will hear about it. Sarah, Bryan and Adam are going to go over the following questions:
- What makes truly great documentation?
- What is the difference between the bare minimum and exceeding users' expectations?
- How do you account for multiple audiences?
- What is the business risk of having poor documentation?
On today's episode, our hosts Sarah and Bryan are chatting about Documentation with Adam Wathan from Tailwind CSS. To talk about this today, we invited (for the second time in the show) Adam Wathan, creator of Tailwind CSS. Tailwind is a CSS framework optimized for building custom designs really quickly without having to start totally from scratch.
Documentation is a tremendous topic, especially in tech. We often joke that "people don't read the docs". But when documentation is judged insufficient by the community, you will hear about it. Sarah, Bryan and Adam are going to go over the following questions:
- What makes truly great documentation?
- What is the difference between the bare minimum and exceeding users' expectations?
- How do you account for multiple audiences?
- What is the business risk of having poor documentation?
Adam Wathan I kind of feel like documentation is the most important thing for the success of basically any open source project. Unless you're doing something that there's no alternatives to, then the way that you compete is on developer experience effectively, right? And documentation is a huge part of that. If people just can't be successful with your tool, then they're going to get frustrated and not use it. So I think for us it's been really important to invest in that so that people are actually successful with the tool.
[intro music plays]
Sarah Dayan Hi everyone, and welcome to Developer Experience, a podcast by Algolia. We chat with guests who build products for developers about their developer experience strategy, what it means for them, why it's important, and so on. I'm Sarah Dayan and I am with my co-host Bryan Robinson. How is it going, Bryan?
Bryan Robinson It's going great. How's it going with you, Sarah?
SD Pretty well. I'm really excited about today's topic, it’s one of my favorite topics in the world. So on today's episode, we're going to talk about documentation. A really tremendous topic, especially in tech. In tech we often joke that people don't read the docs, but when documentation is judged insufficient by the community you will hear about it. But what makes truly great documentation? What's the difference between the bare minimum and exceeding users’ expectations? How do you account for multiple audiences? And what is the business risk of having poor docs? So to talk about this today, we have Adam Wathan, creator of Tailwind CSS, who is returning to the show. Hey Adam!
AW Hey! Thanks so much for having me back.
SD So Adam, can you give us one one-liner about Tailwind for those who are not familiar with it?
AW Yeah. So Tailwind is a CSS framework optimized for building custom designs really quickly without having to start totally from scratch.
SD So Adam, you were in the pilot of the show to talk about what is developer experience. And I remember that at some point we briefly touched on documentation. But since then, you've kept busy and you recently released the v3.0 of Tailwind CSS with a massive revamp of the documentation. I'm a Tailwind fan so my objectivity is clearly skewed, but I've also worked on the Algolia documentation for several years before I moved on to another role. And from my experience, my personal point of view, this iteration goes straight to the top of the leaderboard of tech documentation. Period. So I'd love to know, can you take us through your thought process and the guiding principles that you followed when you were designing these new docs?
AW Sure. I'm trying to remember what some of the main things that we wanted to improve were. The motivation for it in the first place was really just that we were releasing a new version of Tailwind which of course had some changes and stuff. So we had to update the documentation and we wanted to update the design, but it's hard to touch that stuff without also wanting to improve every other little thing that you see that you have better ideas for now than you did in the past. It all started with just needing to make some of the necessary changes based on some of the changes in the framework. But every page that we saw, we tried to figure out ways to improve it. And there was honestly lots of things I wanted to improve that we still haven't had a chance to improve and maybe that would be an interesting topic to discuss today as well. One of the big things that we wanted to improve in the documentation was a lot of the little visual examples that we provide for all of the different CSS features. Because a lot of them just weren't very accurate or clear or just didn't look that great. So we invested a lot of time into that and it was an interesting challenge, because I think one thing that we learned working on this project is, developers especially, and I'm as guilty of this as anyone, really want things to be just so consistent all the time. We just value consistency and systems and things being almost as automateable as possible. But for documentation, I don't think that's necessarily the right approach. For a lot of the examples, it makes sense to explain something like say, some of the Flexbox properties, like justify content and align items, with sort of abstract examples with little boxes that just sort of show where things move to when you change some of these properties. But for other properties, using abstract examples doesn't teach you anything. You might see how something changes, but it doesn't clue you into why you would ever want to do that. So for this iteration of the documentation, we have a very interesting mix of really abstract examples and real world examples that try to show why you might want to use a feature like this in real life. One example is pointer events, which is almost a pretty obscure CSS property. If you're not writing lots of CSS and doing lots of front end stuff, but coming up with an abstract example for showing how, when this square is in front of this one, and you try to click on it, you can't click the thing behind it, or now you can. I don't know that people would look at that example and understand why that property even exists, you know? So why would I ever want to be able to do that? So instead we tried to come up with a real world example, which in our case was a little custom search input that has a search icon on it. And you want to make sure that the search icon isn't sitting on top of the input and not letting you click through to the input behind it. That's one example. We did some stuff with examples like overflow, to show how you can use overflow to crop images that might otherwise poke out of a container, stuff like that. So that was one of the things we focused on a lot for this iteration. The other things were really just trying to improve the stuff that was already there in certain dimensions. And there's a lot of things that I think were already in place in the documentation that are still things that I would encourage people to work harder at that are maybe things we can talk about too. For example, one of the things I really value in our documentation that again is unintuitive I think for a lot of people, is the equivalent of denormalizing your documentation the way you might with a database. Instead of trying to make sure each concept is only explained in one place, we repeat documentation tons and tons and tons of times. So for example, if you want to learn how to do responsive design with Tailwind, you want to know, “How do I change the background color at a certain breakpoint?” Those sorts of things are explained probably on over a hundred pages in the documentation. At the bottom of every single CSS utility page it explains, "This is how you do responsive design with this feature. This is how you do hover and focus and stuff." And we could just have not put that there and hoped that people found the more central pages that explain that and tried to explain in an abstract way that any utility can have ‘md:’ added to the front of it. But I think it's more helpful to see a really concrete example for that specific page. That's something that we do a lot in the documentation, and I think one of the things that made me realize how important that was, was recognizing that most people who visit your documentation don't find it from the homepage. They're not starting from where you think they're going to start. They're starting from a Google search and landing on a page. That's become their entry point to the site. So you almost have to think of every single page in the documentation as possibly being the first documentation page the person has seen and thinking about how that influences how you structure the documentation. How do you make sure they can find what they need? So it's more just like this big graph than it is like a linear journey.
SD Absolutely. It's funny because last episode we talked about accessibility and we were weighing developer convenience versus developer experience, and how they can clash at each other. But I feel like, especially as you were talking about it, that documentation is the one place where if you really value your developer convenience, you're not going to have good docs. Because ultimately yes you could say, “I want to just have JSDoc or annotations in your code and that's going to generate the documentation and this way everything will be in one place.” But ultimately, that's not how you're going to have good documentation. You're going to have good documentation by having it extremely handcrafted, thinking especially for that concept, does it need to be in multiple places? But how do I make sure that it's easy for me to update? So your fear of not being able to maintain your documentation might actually hinder having a great product. And so you were mentioning those visual examples, that you already had them, but you made them even better. That's one of the things that I loved the most, not only they're gorgeous, but for something as visual as styling, it's bulls-eye, of course. Like, know thy domain, of course. You're talking about CSS, you want to see what it looks like, but at the same time people could say, “Oh, it's not Tailwind's responsibility to teach CSS and people should be expected to know what a style does.” But yes, this is a valid criticism. It could be a valid argument. Especially if you do not want to put up the effort, that could be a good excuse. But at the same time it does turn a blind eye to the reality that some people learn CSS through Tailwind. Some people do. And even seasoned CSS developers don't know the entire CSS API. So realizing that your product may do more things than what you think. Like Algolia, some people discover search and search concepts and vocabulary through Algolia. They are not necessarily seasoned in what is a fricking search engine. So taking that into account and understanding that documentation is not a description just of your product, but education through maybe a world that people are discovering all at the same time through your product, to me, is definitely one of the things that makes great docs.
AW I one hundred percent agree. I think the point you made about the JSDoc stuff is a trap that people fall into all the time. You want to just write API documentation and expect that everyone's going to succeed with that and they basically never will. I think that describes a bigger mistake that I think people make a lot of the time, which is to focus on trying to explain how things work with their tool instead of focusing on what problem that users are actually trying to solve. Because if the solution to doing X with your tool is Y, nobody knows to look for Y in the docs. All they know is that they're trying to solve problem X. So we work really hard in the documentation to do everything that we can to make sure that people find the right answer for the problem that they're trying to solve. And there's a bunch of things that play into that. One of them for example, and I could be convinced that maybe we could do this differently or better, but one is recognizing that not everyone uses the same name for everything. So in the Tailwind docs, for example, you have words like responsive design, and you have words like breakpoints. There's multiple ways that people describe things. So in our documentation, we deliberately try to mix up that terminology and use both here and there, especially in headings, so that our doc search integration will crawl that stuff. So if someone searches for breakpoints, they might find one of the H3's on the responsive design page, but at least they land in the right place. Another thing that we do in the docs is if there's something that you know people want to do with your tool, but your tool doesn't actually support or the solution is totally different, we still make sections in the docs for that problem just to have an opportunity to explain, “What you actually want is this other page over here,” so that when people are searching for that they find it. Another thing we've been looking into and experimenting with, but I'm not sure if we've actually deployed any of it yet, is trying to be more deliberate about adding aliases for different things into our search stuff. So if you might do Command+K and type ‘breakpoints’, but the first result is responsive design, it doesn't actually match the word breakpoints at all but it still shows up because you've tuned the search that way. We do that a lot on the heroicons documentation. Well, it's not even really documentation, it's just a search interface. So if you're searching for an icon for a ‘+’, you might type ‘plus’, you might type ‘add’, and we want the icon to show up no matter what. Just trying to figure out ways to do that has been really helpful I think for people. Again, it's such a pitfall to run into to be trying to describe the features of your tool instead of the problems that those features solve and it just creates this really big chasm that people have to cross to get to the actual answer a lot of the time.
BR Speaking of chasm, so Tailwind is a relatively newish product, right? I mean, it's not been on the market 15+ years or anything like that. And I wonder, is there anything that y'all had to look into in recrafting the documentation around going from a stage of early adopters, which is probably where Tailwind was two years ago, into the mass adoption that Tailwind has seen in the past few years? You've gone from people who are very passionate about integrating with Tailwind, they're the ones that joined in early on, to people who are just trying to get the next task done because they've recently integrated into a code base with it. Is there any big changes you had to make around that?
AW I don't think we actually have changed a lot there, but I think there are opportunities to change more there. One thing we do talk about a lot internally is that, early on, because the tool was really new and nobody was using it, it was more important to convince people why they should use it to actually get them to give it a try. Whereas now I think there's enough momentum that we don't have to do that as much and we can focus more on just explaining how things work and being a little bit less defensive in the documentation. One example is there's this apply feature in Tailwind that people use to access Tailwind values and their custom CSS. And we created that feature in the beginning because it felt like an important bridge that was necessary to help people feel comfortable even trying to use utility classes and stuff. They didn't want to just make this leap. They wanted to be able to keep one foot in the comfy area. One thing I've been trying to do more with this documentation, slightly actually, is deemphasize some of that stuff a bit more because I think Tailwind has a stronger reputation now for just being something people like and people are successful with, and I don't think we need to surface those features as much because people are more willing to just give it a try based on the sort of social proof that's out there around it now. Which is good because I think people can abuse features like that and actually create code bases that are harder to maintain just because they're trying to stay comfortable. So that's one thing that we have changed a little bit. For example, on the v2.0 docs, there was a section called ‘Extracting Components’ that explained what to do when you run into a lot of duplicated styles. And the first thing that we recommended was using apply and extracting classes with CSS. And then we sort of explained how you could extract React components or template partials and stuff. And for this iteration of the documentation, I totally redid that whole section. I renamed it to ‘Reusing Styles’, which I think is a clearer name. It actually starts now by explaining how to use multi-cursor editing to deal with duplication, which I'm a little apprehensive about because I've already seen people roll their eyes at that. "Oh wow. This tool, the only way to maintain it is to use multi-cursor editing." But it's not actually true but it is the best solution in so many cases. If you just have six classes repeated in seven <li> items, right on top of each other that can all fit on the screen at the same time, it really is easiest to just edit those six lines at the same time instead of introducing any costly abstractions. But after that, we talk about extracting React components or Vue components or template partials. And then at the very end we talk about creating custom classes to wrap things up and we explain how to do it with apply. But there's also a big caveat that explains, “Don't do this just because you're trying to make your HTML cleaner, because that's actually going to make your life worse.” I'm highly considering in a future iteration of the documentation, making that simply about creating custom CSS classes, and reference using Tailwind features like the theme function to reference stuff in your config file, just to avoid sending people down the wrong path by showing something that looks so cool and sexy, but is actually a tool that you should be reaching for that often. And I'm starting to think it would be worth introducing a little bit of friction there. That would have been a bad idea at the beginning because it would have caused less people to try the tool. But now that people have enough other motivation to try it, I think we can introduce friction in the places that might lead to a better long-term experience.
BR So when it comes to that right versus wrong path, almost like you can go either way and Tailwind allows for that. How do you balance the documentation with the philosophical conversations? Right? Because utility first, not everyone's familiar with even though they might be super familiar with Tailwind.
AW We try to just litter a few things throughout the documentation here and there to add a slightly more opinionated take on things. And we also try to just use examples that imply the usage that we recommend. An example of that was when we were updating the actual documentation for the apply feature itself. It used to have a bunch of examples about how to create your own buttons and stuff by applying all these Tailwind classes, but I changed all those examples to actually be about styling third party widgets, where you literally have no ability to style this JavaScript library that you've pulled in other than to target their existing selectors and apply styles to them. And this can be a way to feel like you're writing Tailwind, even when you're targeting stuff where you don't have access to the HTML. So that felt like a use case I could get behind a little bit more strongly when it came to that. Honestly, I think we could do more of it. Something that we've talked about doing that I think would actually be really fun and I think people would get a lot of value out of, is adding little call-outs to the documentation that are sort of like ‘Adam's Take’, you know, that have a little illustration of my face or something that can be a lot more personal and say, like, "I would use this here. I would use this there." And it sounds a little silly or something, but I do think if I put myself in the shoes of someone trying to learn a framework, say I was reading the Vue documentation or something, and there was little ‘Evan's Take’ bubbles, I would be really interested in reading those. You know what I mean? So when I'm thinking about doing myself, it feels kind of cringy and narcissistic or something. But when I put myself in the shoes of someone reading another documentation for another tool, I totally see the value in it. And seeing those real life personal recommendations come through, I think can make the documentation, maybe feel a little less professional or something, but I don't think that has to be a bad thing. I don't know if either of you remember those Head First books, like Head First Object Oriented Design, or whatever, by Kathy Sierra and some of the other people that she worked with. They always had this really quirky style of lots of pictures of people with speech bubbles and stuff and it was really silly but the concepts really stuck. You know?
SD I think what really matters is execution when you do something like that. But depending on the way you market your company and your product, and whether your person is a big part of how you talk about it, then definitely for Tailwind you are also the face of the framework and of your company. I think it can work. We have so many examples of that, like, the Rails manifesto is definitely oozing DHH's personality. There are other examples, like Formik, for example, in the documentation you can find some really interesting, fun stuff. I know that the useFormikContext hook, which is something that is not recommended to use, has this slide on it which says, “Use this hook if you're Jared”, referencing Jared Palmer. And that's funny and it happens here and there and that's okay because this library is associated with Jared. And at the same time when you're using something, and you're not sure whether you should touch this or that or if it's dangerous, sometimes you want to know, “What would Evan do? What would Jared do? What would DHH do? Or what would Adam do?” I think it can be really comforting to know when you have multiple options or when something is so abstract that you have to make choices, what is recommended or what do other people do.
AW Yeah, I totally agree. I am so often paralyzed by those sorts of decisions when I'm using other tools. Anytime there's two ways to do something, it's like, "Oh no. What way am I supposed to choose?" So that's something we think about too in the documentation, is trying to, whenever possible, only explain something one way. And I can be convinced that this is wrong, but there are things that we have deliberately left out of the documentation because they are very advanced-use sort of things that make the stories more complex and confusing for the 99% of people who don't need that stuff. And anyone who does need it will find it as soon as they Google it because there'll be a GitHub issue or discussion or something that surfaces that API. And probably it would be good to figure out a way to include that stuff in the documentation, but I don't think it's a good idea to just jam it in there without being really considerate about how it impacts the people who don't need to know that stuff because another thing we try really hard to do is to explain things in the most terse, but clear way possible. If I can explain something in a sentence instead of a paragraph, I'm going to do that because you're just more likely to read it. I think just designing the actual documentation experience in terms of how you structure the content really matters too. Mixing up the formatting so instead of just paragraph, paragraph, paragraph, paragraph, paragraph, trying to figure out ways to do like, paragraph, sentence, bulleted list, code sample. Something to just keep it visually fresh so you're less likely to skim and miss the things that you need to see. Trying to bold things and italicize things and just really trying to make it easy for people to pick out the stuff that they need to see to find what they're actually looking for I think is really important. Another little detail is always trying to show as much context as possible in code samples. One thing I hate when I'm reading documentation is when they show a code sample, but they've stripped out everything except the exact thing that they're trying to show you. So often I'm left wondering, "What file is this even in? Where am I supposed to do this? I have no idea. It's so implicit." So we always make sure to show the file name whenever possible or an example file name. So if it's something that's being done in your Tailwind config file, there's always a little thing at the top of the code sample that says tailwind.config.js, and it might be obvious but at least it's there and you know. Even if we just want to focus on some small area of the code but it's more clear what you should actually be doing with the surrounding context, we'll dim the surrounding code and highlight just the thing that you're supposed to look at rather than actually deleting it. And little details like that I think can go a long way too.
BR I think more doc sites should use that highlighting functionality. I think that is such a great way of showing context that makes so much sense.
AW Yeah, we had to build lots of custom tooling to even do that. There's lots of things where we're not even trying to highlight full lines of code. We're just trying to highlight one class in the class list. So we have all these custom markdown extensions in the docs, so that in HTML snippets, we can just put two asterisks on the side of any piece of code and it'll almost treat it like markdown and highlight it. We have components set up so that we can create code samples that have multiple tabs for example, and that sort of thing. We even do stuff where, at least in one section of the docs, instead of having a static code sample, we have an animation for showing the multi-cursor editing stuff so you can actually understand what's happening. And some of those things are really hard to justify investing in when you're a solo person working on an open source project in your spare time, of course, so you have to figure out the right balance. But I found being able to invest in really custom ways of teaching things has been really awesome, even though it's of course a big investment. I think someone who does this really, really well is Josh Comeau who does a lot of CSS teaching stuff. Almost every article has totally custom tools in it. He's got a great one on showing you how easing curves work and stuff where it'll show the ghosted versions of things that are moving and making custom tools to teach things like that is so powerful even though, of course, it's a huge investment. But if you have the time and can justify doing it I think it's worth it for sure.
SD Yeah. Shout out to Josh Comeau, definitely, who's really great on demonstrating how so far we probably really poorly use the website media, like documentation has been just text and images sometime for so many years, while we have the ability to make it whatever we want. Like, people can interact with it. I don't know if you had that when you were a child, but I learned stuff through CD-ROMs at school. And you could click on stuff and it was super interactive with really quirky animations. And then we moved into an era of websites that were super standardized and super boring with just text and images and Josh's website is really a demonstration of how we have the tools and the power on your phone or on your computer to make stuff really custom from one thing to another. And you can spend some extra effort creating something bespoke for that specific topic you're talking about because it's going to reward you tenfold, especially the person reading it.
AW Yeah, and I think there's a lot more we could do in that regard. We try to do a lot of it already. An example that I think is really nice is, we have a lot of code samples that are resizable, so we've created an abstraction for the resizable demo area, which is often really helpful. So for a concept like flex-grow for example, you could just show a static example and you could probably figure it out. But if you can just click the drag handle and resize the demo, it's like, "Oh, okay, I see exactly what's happening here." Stuff like that is really, really helpful. For our cursor documentation, we had James on the team draw custom cursors for every single cursor type because I just couldn't find a good reference for them anywhere. And if you hover over them it'll show you the actual one that you would see on your operating system which is cool too. So we do as much stuff for that as we can really think of and I think it goes a long way.
SD There is no such thing as the developer persona. I think that's something that we can all agree on. People have widely different backgrounds, even if they are all programmers, they have different amounts of experience, different habits, et cetera. And even for a CSS framework you might think, “Oh, yeah that’s a developer who touches CSS,” but you could have seasoned front end engineers who are reading the docs. You can have back end devs that are making their own project and they have to do the styling themselves and so they heard Tailwind is great. Or you can have beginners who are trying to learn CSS through Tailwind. You can have people who like other methodologies, like CSS in JS, and they want to peek at alternatives. So there is no such thing as one developer reading your docs. There are a multitude of people reading the docs and I'd love to know, how do you address multiple audiences without muddying the point or making some guides three times longer than they should be?
AW That's a really hard problem and I would like to find ways to get better at it. But I can give one example of something that we've done in this round that I think has helped a lot, which is sprinkle in these sort of detailed summary widgets throughout the documentation. So we sort of default to the ‘assume the person is experienced’ experience to keep it as short as possible by default, but sprinkle in opportunities where someone can click something to expand something that goes into a lot more detail, and a lot of time the thing that expands is four times longer than the section that it's in. But that way you're not introducing that into the experience for every single person. That's one thing that has helped a lot. I think one other example is on all of the utility pages we have that little table at the top that lists all of the classes. And a lot of people are just coming to that page for that. But it's also not really that useful to someone who doesn't really know CSS, so we have to figure out– where does it go? Does it go at the bottom? Or does it go at the top? If it goes at the bottom, now everyone who's just trying to remember what the name is has to scroll to the end of the page to find it. That's sort of annoying. But if we put it at the top, then someone who's trying to learn how this stuff even works might have this giant table they have to scroll past before they can even see an explanation that is trying to actually teach them what the things actually do. So that's a simple one because the answer is really just to make the table scrollable and keep it set to a specific height. So when someone's visiting the page who needs the explanations, they can see that the detailed explanations are still there above the fold, but someone who just wants the class names can see them at the top as well. This was harder to solve on mobile because creating scrollable areas on mobile is a bad experience a lot of the time because you kind of get trapped in them and you have to scroll to the end of the table before the whole page will start scrolling again. So we tried to think through that experience too. And what we came up with was on desktop, the tables are scrollable if they're long. But on mobile, they're just truncated with a button that just says expand to the whole thing. And for some of them they're really, really, really, really long, like the margin page, it's like hundreds of options there. So we keep a button just at a fixed position to the bottom of the viewport that lets you collapse that table when you realize that this is ridiculous and I don't actually need to be looking at all this stuff. So we have tried to think about that stuff as much as possible, how to provide more detail for the people who need it, but not force it upon the people who just need the concept explained. Another way we've done that is on the documentation, explaining all the different hover and focus modifiers. There's so many of them in Tailwind 3 that it would take you forever to get the high level overview if we tried to explain every single one. So we've started doing things where we add appendices to certain pages that go into more depth or give every single example. So we did that for that page because there's so many pseudo classes like hover focus, focus, then focus-visible, active, visited, target, first, last, only, odd, even, first of type, last of type, only of type, empty, disabled, checked. There's dozens and dozens of them so it would be annoying if you have to get through all of those just to learn how to do a before and after pseudo element. So we try to keep each section a little bit tighter and more high level and put more of the details at the end in cases like that. It's a hard problem figuring out how to find the right balance. I will say I think an important thing to consider is that the worst thing you can do, I think, is to try and come up with the average experience, because there's probably no average developer. I think there's a famous story about how they were designing cockpit seats in airplanes and they took all the measurements of all these pilots and averaged them all and made a seat and not a single pilot found it comfortable because no one was that size. It's a distribution of people's sizes. So that's where the adjustable seat was invented. I think it's important to try and write the documentation for a specific person and do that several times and try to just put yourself in those person's shoes and not try to necessarily compromise, but figure out ways that you can target multiple people directly at the same time through things like progressive disclosure or figuring out how to make sure things don't get in the way for the people who don't need them, but are still there. Otherwise you ended up writing documentation for nobody, I think.
SD Yeah. I really, really love that take. And the title of this podcast is Documentation is a Product. And I think that line of thinking is exactly in the mindset of how you build a product. I have a Herman Miller chair that I spent a lot of money on after spending so little money on crappy chairs that really ruined my back. And what I love about it is that the experience of just sitting in it will be fine for most people. And it will be thought, in a way, that is supposed to be great for the widest audience, but at the same time, it's adjustable and I can customize it to exactly what I need without risking messing something up. That's what you find in Rails as well. Rails pioneered the idea of great defaults that you might not even want to change, and then you can tweak some things, but they pioneered that. And it's no surprise that so many other frameworks that are successful, like Laravel, or Blitz is coming up right now, are based on the ideas of Rails. And I really like this mindset of, “Don't try to average it out,” thinking that it will give you the compromise, or the middle ground is probably where the truth is, while acknowledging that there might be one great way, but then acknowledging the fact that people are different and providing them with the ability to adjust exactly to their needs and finding the path to those adjustments not being a horrible experience, is definitely more work, but probably a much better experience than trying to just sum it up and average it all.
AW I think it ties into something we talked about earlier too, which is if you take that approach, it forces you to introduce a lot of redundancy into the documentation, which I think is in our nature to resist, but is actually for the best. Most documentation sites actually do a pretty good job of splitting out guide style documentation from API reference documentation. And once you really know a tool, like I worked with Vue for years and years and years, and at this point I'm only really looking at the API documentation because I just understand the concepts really well and I want a one page ‘Command+F’-able sort of reference for things. But the guides are obviously more helpful for people who are trying to understand, "How does this thing even work? What are the concepts? What is the mental model?" And that's something I think we could do a better job on with the Tailwind docs, actually. I've wanted to create some sort of API reference style cheat sheet thing. I know there's a lot of community created ones that people really love, and it would be awesome to create a first party one where it really is just every feature of the framework on one big, long page with really tight examples so that you can scroll through them. It doesn't explain anything, it's designed for the person who knows how the thing works, but just is needing to find the exact feature that they're looking for. And then in the opposite direction, I'd also really like to add more guides to the documentation that are less about, "Here's a CSS property and what it does," and more about, "Here's a styling problem you have and here's how you would solve that with Tailwind," because that's something that we're sorely lacking and it's been on my to-do list every time we redo the documentation and it just gets kicked off because I don't have time to do it until the deadline. So even when we were doing the v2.0 docs I wanted to do it and I wanted to do it again for the v3.0 docs. But for example, I find it so embarrassing that there's not a single page on the Tailwind docs that has a title of ‘Flexbox’. We don't have a Flexbox page. We have a justify content page, we have a flex grow page, but we don't have anything that just tries to teach you what Flexbox is, what it's for, what problems it can solve, and introduce you to some of the high level concepts. Same with grid. I'd love to have a documentation page on just working with color in Tailwind and here's how the color palette works, here's all of the different ways that you can use it. Here's how you create gradients on the same page or styling forms. There's no form utilities or form CSS properties, really, so to speak. But it would be nice to have one page that explains, "This is why you might need to use the appearance-none utility,” or things like, “The resize utilities can be helpful for text areas if you don't want people to be able to resize them horizontally,” just sort of co-locating related things under an umbrella and explaining them in that context. And that might mean that we explain the same utility in five different places but through a different lens. I'd love to have a page that's ‘Accessibility’ because there's lots of features of Tailwind that you can use to build more accessible websites, but they're not brought together yet into one place that gives you a bunch of information. So that's a project I really want to take on this year at some point that I think would help a lot of people who aren't super experienced with CSS. Because the target audience for Tailwind in the first place was definitely, “You're sick of writing all your CSS totally from scratch because frameworks aren't cutting it for you because you're trying to do fancy custom stuff.” But now so many people use Tailwind that identify as like, “I'm a backend developer who hates front end stuff but when I do have to do it I want it to at least look decent and Tailwind has nice shadows,” you know? Still lots of room to improve, I think.
SD Yeah. What you're mentioning is basically also acknowledging the ‘why’ of what you're doing and not only the ‘what’. At some point you can teach your service, teach your product, but Tailwind is, if you look at it really through a narrow lens, it's a utility for CSS framework. But ultimately the higher goal of Tailwind is to help people design and style their websites better and that's not only through the code it's also like, better color pairings and that's what Tailwind UI is here to do. It's also maybe demystifying accessibility and stuff like that. It's really important at some point to also realize what is the goal of people going here. It's not only to use utility first or to use your product, it is to make something great and they might have other issues that are not related necessarily to using your product, but having that here and seeing that you are an expert in it also creates more trust. Having documentation in Angolia telling you what makes a great search UI, and what are things you want to do and what are things you want to avoid, helps you because ultimately you're not here just to learn how to cobble together some instant search components. You're here to understand what are the things that I don't know and that I need to know in 30 minutes to make my search because that's all the time that I have for that. So I know that you have personally spent a great amount of time on these docs and yet you’re the Tailwind CEO. So you probably have a lot of other things on your plate than only the documentation. So I'd love to know why do you think great docs are so important for a technical product but from a business perspective? And what is the cost of not caring about your docs?
AW So there's a couple of specific points. I think the first one is that I feel like documentation is the most important thing for the success of basically any open source project. Unless you're doing something that there's no alternatives to, then the way that you compete is on developer experience effectively, right? And documentation is a huge part of that. If people just can't be successful with your tool, then they're going to get frustrated and not use it. So I think for us, it's been really important to invest in that so that people are actually successful with the tool. Tailwind was not the first utility-based CSS framework. There was Tachyons, Basecss, Atomic CSS. There was lots of different stuff out there. And I think probably the biggest difference is our documentation versus anything else. I think there was just a lot of stuff that you had to figure out yourself with other tools and with Tailwind it's there and teaches you how to do it. And it's just increased the odds of people actually being successful with the tool and just being happy with the tool. I'm trying to think if this is really as relevant as I think it is in my head, but there's this book, Badass by Kathy Sierra, that's really great. And she talks about how, if you make cameras, your job isn't to make the best camera, it's to make the best photographers, you know? And people will rave about your product if they feel like they can say, “Look what I was able to do with this thing. Look at this awesome photo that I took with this camera.” So documentation is such a huge part of helping people be a badass with your tool. You want people to be able to say, "Look at this website that I made with Tailwind. It was so easy because all the information I needed was easy to find and explained well. And I've never been able to figure out how to do responsive design before, but look how I made this site and it works on mobile and it's the first time I've ever been able to do that. How cool is that?" You know? So I think it's really important just for the success of the actual open source project and for adoption. And then the other reason is just that our documentation is our biggest traffic source for our commercial products too. So all of our traffic for Tailwind UI, for example, comes from Tailwind CSS and Google, and tailwindcss.com sends us more traffic than Google does. So it's really important that we keep making it better for that reason too, because that's how people find the things that we sell and make it possible for us to even work on Tailwind by actually running a sustainable business. So our documentation site is the most important thing that we have, and it really has to be great for Tailwind to be something that people actually use and for developing Tailwind to actually be sustainable.
SD I love what you said about the camera example that reminds me of a quote of Sean McCabe on his seanwes podcast. I'm going to butcher it, but it's something like, “When you market your product, don't market what people can do with it. Market the person that they will become after taking your course or using your product.” I think it makes so much sense. Ultimately people don't care about Tailwind. They don't care about Angolia. They care about their product and how they are going to be able to improve it, or how good it's going to make them look towards anybody else. And also when you look at things, we're in the boom of the tech-as-a-service era, we have AWS and GCP, Netlify, Vercel, Prisma, PlanetScale, all those services that allow you to spend time on the thing that you know, and have the rest handled by smart services. And I feel like there are going to be less and less tolerance to products that are really complex to operate because at some point someone will abstract it well and steal the market. So even if you're doing something really smart, you're fixing a really hard problem, kudos, but at some point maybe you're the first, but you're not going to be the only one forever and someone else will figure it out. And if you don't have another big differentiator, which in this era with developers and especially with developments of software development being more and more accessible to all kinds of people, if you're not accepting the fact that your thing has to be easy to use, friendly to use, people need to be able to go from zero to "Hello, world!" in the smallest amount possible. And that there is nothing cool about mastering something really obscure, or really complex. Somebody else will understand it and is going to steal the market from you. Another thing that like, I see it with the Tailwind docs, is that more and more people are becoming averse to marketing bullshit. It used to be a saying that we have about developers, but I think there are many more people that are not writing production code, but maybe still technical, like product managers or support agents. They don't write code. They're not the ones who are going to use Tailwind, but they would go straight to the docs because this is where they will find the most straightforward information on most sites. So you will not go to .com, you will go to .com/docs because this is where you know you will find what you need without having to wade through all the fluff. So realizing that your docs are becoming the face of your tech company owes almost as much, or maybe even more, than your dot com is also a realization that more people need to make.
AW Yeah, I agree. For the v1.0 version of the docs we didn't even have a landing page. We had like a hero at the top of the page, but after you scrolled past that you were in the docs which people really appreciated, I think. For the more recent versions of the documentation, we do have more of a traditional landing page, but it's not really the type of content that I think a lot of people would put on their landing page– which is trying to sell the tool or trying to show how many companies are using it or any of that stuff. Our goal with the landing page for Tailwind is that if you read the landing page from top to bottom, you probably already know how to use the framework now. First of all, there's an animation at the top that just kind of shows exactly what the workflow is like. And then it explains how to do responsive design, it explains how hover and focus styles work. It explains how you deal with duplication and stuff like that, but done in an exciting and very highly designed sort of way. So it does double duty as documentation and flashy marketing page sort of stuff. But the whole job of the page when we designed it was really just to explain how to use the tool. The goal was that someone could read the page from top to bottom and feel like they know enough to start playing with it. I've seen a couple of sites that I thought did a really good job at that. One that I always used to come back to is the Popper.js documentation. This was actually probably my biggest inspiration for doing the Tailwind docs the way we did, even though I don't know that people would necessarily make the connection if they saw it. But I love that when you get there, there's an exciting designed hero with some personality and stuff and a bit of a brand, but all the content is just showing you, this is what the tool can do, and this is what the code looks like, and here's a demo of it. The Framer Motion homepage is a good example of this too. Those are probably my two favorite open source tool homepages because they really know their audience without completely throwing away the opportunity to have a fun and well-designed experience.
BR At that point it becomes a part of your documentation but it is not itself the documentation.
SD So if there is bad documentation out there, it means that there's likely a lack of either care, time, or maybe even skillset dedicated to it. According to you, what makes documentation hard? And what are the skills and strategies that you would need to invest if you want great docs?
AW I think a lot of this is a lot of the things that we've talked about already. The fact that you have to serve multiple different audiences. You have to figure out how to connect the dots between the problem that people are actually trying to solve and how your tool actually solves it. Those are hard. Another thing that's just generally what I find to be the hardest thing, the absolute hardest thing, is just the information architecture of the documentation. So just trying to decide where to explain things and what order to explain them in is impossibly hard. It's like the hardest work I've ever done in my life. I've spent like two weeks on a single page without writing any content, just trying to get the table of contents right for that page. Just, “What order should this go in? Should this be explained with this, or should it be explained with this?” And it's so hard because it's not linear, but you have to try and explain it in a linear way. So you have to figure out how to create a page that someone could read from top to bottom, even though the thing that they're looking for might be three quarters of the way down the page. It's so hard to get that stuff right. And when you do get it right, it always looks so obvious at the end of the day and everyone would think you have to be extremely stupid to have struggled to get it to that point. But it's so much harder than you think. So I would say stuff to invest in if you want to make your documentation great, I think the biggest thing is just recognizing that the skill is teaching. Like, documenting and teaching, the difference is maybe subtle but to me it's an important difference. Documenting is just trying to write down how something works, but that's not enough for the documentation experience to be really great. You really need to try and empathize with the problems that people are trying to solve and explain how your tool solves them and try and predict every problem that someone is going to run into and just really think about things from the other person's point of view. A piece of advice that I read a long time ago that really helped me was, always writing for a specific person. Not even for a persona, but literally a human being that you can identify. It's very clarifying when you think, "Okay, I'm teaching my friend Alice how to do this. I know what she knows and what she doesn't know and what's going to make sense to her." There's lots of people out there that are going to be like that person and maybe you can think of a few different people that have different levels of experience, but just really thinking about that specific person really helps, I think. I think the other thing to recognize is that documentation is never done. It is a living thing and you should always be looking for opportunities to improve them based on common problems and questions that come up. So anytime someone opens a GitHub issue that isn't actually a bug, but just something we need to explain, I always try and figure out, “Why did they open this? Where did they look that they didn't find the answer?” And I'll often ask people, "Where would you have expected to find this in the docs?" And I'll figure out a way to put it there. And that can be tough sometimes because it feels like you're making a mess of things because you're adding things to the docs that you don't think even need to be there, but they do because people need that information, or people are expecting something to be there that's not there, and you need to explain why it's not there, which means there needs to be something there. So I think that the other element is actively grooming and maintaining your documentation and figuring out ways to help people get answers to their questions in a more self-serve way and that'll make your life better too. Because if you're running a popular open source project, the hardest part about it is just keeping up with all of the questions and issues and stuff from the community. So figuring out ways to address that stuff up front is really important and keeping your documentation in good shape is the best way to do that. So I would say invest in becoming a better teacher and thinking about documentation through that lens and finding resources to do that. Think about things from the perspective of someone using your tool and thinking about specific people. Obviously it's important to practice your writing skills and figuring out how to communicate clearly, and clear is the best way to think about it, I think. You're not trying to be thorough. You're not trying to be terse. You want to be clear and that sometimes means you have to write a lot. Sometimes it means the best thing to do is write as little as possible. Making things clear, I think, is the goal.
SD Yeah, that was my point. Invest in your writing skills. In addition to teaching, this is a skill that’s personally my favorite skill ever. If there's one thing for me to master throughout an entire life it would be writing because everything starts there. Knowing how to write better is usually what will help you with everything else. There is a great book too, there are many books about writing, but one that I love and that is relatively easy to get into is, Writing Without Bullshit, by Josh Bernoff, that helps you write getting rid of the fluff, and getting rid of the fluff is also about clarifying your ideas. When you learn how to write better, you also learn how to mind map better. You also learn how to explain yourself better, how to get ideas out of your head to the paper in less time. And the people who write the most usually are the fastest at mind mapping, at finding good information architecture. It's still going to be hard, but it's going to be significantly easier if you actually have practice in writing. And yes, some people don't like writing, but I suspect that like many things, writing is that thing that is so hard, that we don't like it because we're not good at it. And when you get good at it, you start liking it because you realize how empowering it is to find the words really easily to express what you want to say and how empowering and how rewarding it is to have people understand. I imagine that people who wrote the Vue docs, you have Sarah Drasner, a lot of people were involved in that process. But how rewarding it is to have people constantly saying, "The Vue docs are the best. The Vue docs are so easy to follow. I use Vue because it was so much easier to learn than whatever other framework." Like, this is rewarding when you are able to have people understand your vision through your words.
AW Yeah, totally. A hundred percent agree.
SD I could spend honestly two extra hours on that. Let's wrap this up with some concrete advice for people. If someone was willing to improve their technical documentation today, and they want to do all that stuff that we talked about, but they want to start somewhere, what could be like three good concrete steps that they could take before they plan for something deeper?
AW One good one would just be to find somewhere in your existing documentation where you're explaining things from the perspective of the creator of the tool, and figure out how to explain it from the perspective of the person with a problem. We've talked about this a million times, but this was something that we worked really hard on in the Headless UI documentation, for example, because it's so easy to just be like, "These are all the props for the components and this is what they do." We even have a section in one of the components on integrating with Next.js, because if you have to do something where you have to wrap a component in another component so that you can forward some props to it and we could have explained that in a totally different way, but everyone who was running into that problem was running into it because they were trying to use Next.js links component in this component. So figuring out how can we make that discoverable because that's the problem that someone's actually trying to solve, versus writing a documentation section on forwarding props to an existing component. No one's going to know that that's what they're supposed to be looking for, they just know that it's not working in my Next app. That would be one example. I think another one that is something we actually haven't really talked about is looking at the actual design of the documentation. It feels like it is superficial in some ways, but there's a lot of typographic best practices that most developers aren't familiar with that can just make the reading experience a lot worse and make people less likely to even read what you've written. A classic one is just having a really long line length that's like a full width thing where you have to move your whole head before you get to the next line. So investing in trying to improve the actual typography I think can go a long way just towards getting people to actually read the stuff that you've already written so that people are more successful. And let me think what would be a third. I think the point that we made before about sprucing up any examples to be more interactive to make the point more clearly is something that a lot of things could benefit from. I'm just recognizing, like you talked about, that the web is an interactive medium. It's not something that's necessarily meant to be printed. So take advantage of that and think about if there's any way to explain concepts that could be a lot more clear with the ability to actually interact with them.
SD Solid. Bryan, do you have some, especially as a documentation power user?
BR For me, it's all about headings and scanability of code because while I do read more than probably the average internet user, I have fallen into the trap of skipping directly to the code, copying and pasting and being ‘done’, and then realizing, "Oh no, this didn't work because I missed this one little thing that was in the code." So making sure that I can, at a glance, know that I'm about to make a mistake, and how to get away from that mistake, I think is really important. So, know that we like to copy and paste and we want to avoid pitfalls of copying and pasting whenever possible.
AW You know what that makes me think of actually, which would be a fun thing to implement on a doc site? You often have code samples that are like, "Don't do this." You know, and code samples that are, "Do, do this." Make sure that the, "don't do this" ones have no copy to clipboard button, you know? But the ones that you're supposed to use do. That sort of thing. Or maybe copy something nefarious to the clipboard that's like, "Really? Did you even read the documentation?"
SD That'd be so fun. So for me, definitely ties into what you said about caring about what your copy looks like and what you said, Bryan, about scanability. To me, that's the headings, but also learn how to use rich text. Learn how to use bold properly. Bold usually works better if you bold takeaways, not highlights, because people will basically jump through headings, bold, bold, bold heading, and so they should be able to read your page that way. Don't overdo it. Don't overuse bold. Don't put bold everywhere. Don't put italics because there's a reason why you use those those kinds of styles. So yeah, get your rich text down. Understand it. Another one would be one of the things that usually frustrates me with most documentation websites. Triple down on your upgrade guides and watch actual people go through it. One of my favorites is obviously the Tailwind one. I know the one from Tailwind v2.0 which was really well done. Go through that yourself. Actually upgrade from your product the X to the Y and see where it's annoying, see where it's frustrating and have other people than you who don't know as much about your product than you, do it. Because that's where it gets frustrating. You can have a really easy getting started, but then for the power users or people who have been using it for a while, if they feel forgotten about, that's really frustrating.
AW Yeah, I would say on that note too, with the upgrade guide stuff, one of the hardest things about upgrade guides is there's usually so many super minor things that almost nobody is going to be affected by, but you have to document anyways. And if you're not careful, you can create a document that makes people feel like, "I'm not upgrading. This looks like too much work." So thinking about that and trying to categorize the upgrade steps. So you have like, "This is required steps for everybody. This is stuff that probably won't affect you." Something we used to do that we didn't do this time around because I think we were just able to organize in a way where this didn't feel as important, but we'd annotate the steps with how much effort we expected it to be and how many people we expected it to impact. So we have like, ‘effort low – impact high’, or ‘effort high – impact low’. Those are the best case scenarios. Sometimes you have an ‘effort high – impact high’, and that's probably a breaking change you just shouldn't have made. I think that can help a lot too in upgrade guides.
SD Yeah. And it kind of ties into everything that we said, but use your docs. If you don't do it already, use your docs. Build stuff with it, build stuff with your actual product. That's going to be how you realize where most of the problems are. And you can see who uses their documentation and who doesn't. It shows when you pour actual real experience in and when you only talked about it after building theoretically. So yeah, Adam, where can people go to find you online?
AW Best place to find me is just probably on Twitter. So just twitter.com/adamwathan, and you can check out Tailwind at tailwindcss.com.
SD Bryan, where can people go to find you online?
BR Oh, like Adam, you can go to twitter.com, but this time go to /brob. You can find me there. What about you, Sarah?
SD You can find me mostly on Twitter @frontstuff_IO, which is officially the worst username on the internet. You can find my work at sarahdayan.com, and if you want to know anything and everything about the Developer Experience podcast but also Algolia, you can go to Algolia on twitter and on algolia.com. Obviously you can check the Algolia documentation at algolia.com/doc. Adam, thank you so much for chatting with us today. That was a really great conversation, and thank you, Bryan, for co-hosting with me. Listeners, I hope you enjoyed this one, that you learned a lot of new things, that you are inspired to build documentation, write documentation, improve your documentation. Thanks a lot for following Developer Experience and stay tuned for the next episode.
[music plays]
This was Developer Experience, a podcast brought to you by Algolia. You can find this podcast on your favorite podcast platform. We are on Spotify, Apple Podcasts, Google Podcasts, Pandora, Overcast, everywhere. If you want to know more about Algolia check us out on algolia.com and we are @algolia on Twitter.