How to write really good docs

Captions provided by White Coat Captioning (https://whitecoatcaptioning.com/). Communication Access Realtime Translation (CART) is provided in order to facilitate communication accessibility and may not be a totally verbatim record of the proceedings.

JASON: Hello, everyone, and welcome to another episode of Learn With Jason. Today on the show, we’ve got Dan Jutan. How you doing?

DAN: Doing great. Great to be on. Hello, Twitch chat. I’ve been a fan of the show for a while. I remember when Ryan first came on, and I was thinking to myself, one day I’m going to be cool enough to get on a show like Ryan did.

JASON: Well, I’m flattered that my show has become any sort of goal for anybody. You know, it’s a lot of fun to make. I’m really glad that you took the time to join. I think this is going to be a really fun one because we’re talking about documentation today. But before we talk about that, let’s talk about you. So for folks who aren’t familiar with you and your work, do you want to give us a bit of background?

DAN: Yeah, I’m a bit of an open-source fanatic these days. I split my time between Astro, Solid, and other endeavors like Twitch streaming and writing. I got my start in like late 2021 as a Solid team member doing dev education. Eventually, I joined the Astro Core team as well. I did a mix of things, but lately I do documentation mainly and community stuff as well. So a lot of people probably know me from one of those. I see Elian is here in chat, an Astro maintainer. Dave is a Solid team member. So that’s the basic outline of what I’m doing.

JASON: That’s awesome. And I love seeing the crew. Thank you, everybody, for showing up. Dave and Elian. And Aidan and Joshua, hello, hello. But yeah, documentation is one of those things that has, I would say, a complicated relationship for most developers. We all know when we’re on a good project that has great docs because you can feel it. You know what you’re supposed to do. You can find thing when is you’re looking for them. When you have a question, it gets answered by the documentation. We all want that to be true of all projects. Also, when we go to write documentation, we don’t do any of those things. I think to a certain extent, there’s general laziness. Oh, I don’t feel like doing that right now. But I don’t actually think that’s the problem. So I’d really love to pick your brain on this. I’m going to start with a big, open-ended question. What makes good docs?

DAN: Yeah, actually, can I answer about some of the other stuff you brought up? I’m going to get to that one. You mentioned the thing about wanting good docs but not necessarily wanting to write it. I have found that ability to write docs, like skill of writing, of docs writing, and desire to write docs are completely independent variables.

JASON: Oh, interesting, okay.

DAN: I get people so excited to contribute to my docs who are bad writers. And I get people who are amazing writers and will never want to touch docs. They’re an engineer through and through. There are some amazing technical writers who just don’t want to do it. They have the skill set. Part of being a great engineer is being a great communicator. So they have that skill set, and they know how to do it. But they just don’t want to. That is one of the most interesting things about navigating this. Because what do you do with an excited contributor who’s a bad writer? Like, you don’t tell them to their face they’re a bad writer. But you have to deal with them in a different way than if they were a good writer, right? And how do you convince one of those engineers who if they could give you an hour of their time to spend on writing would completely improve the project? How do you convince them to contribute? That is a very difficult part about navigating open-source docs writing. But I’m not sure why but his mic is echoing a bit.

JASON: I just switched inputs. Is that better?

DAN: It’s also very unclear which one of us has the mic problem.

JASON: I think that might have been on my side because I had the wrong inputs going, back from when I was traveling and had to mess with my whole setup.

DAN: All right. Let me do a quick shout out. Shout out to the Solid team members, Astro support mod, shout out to Chris, core team member, shout out to Domit. Anyone I missed, welcome to the stream. Okay. Back to your question.

JASON: Hold on a second. Because I feel like you just out-streamered me. (Laughter)

DAN: This is what I do.

JASON: I never knew that. Such a good idea. Why don’t I say hi to people? Hello, Mandarin. Thank you for coming. I’m terrible at this. Dan, it’s your show now. You take over.

DAN: Cool, cool. Yeah, I’m a Twitch streamer too. I just started a month ago. I’m having an absolute blast. I have a very exciting announcement on my stream tonight. It may have to do with a certain sponsor. But that’s an announcement for later.

JASON: All right, all right. Are you the same user name on —

DAN: Yeah, it’s just Jutanium.

JASON: We’re going to make sure everybody gets over there.

DAN: Yeah, super excited about this. Do you know Tanner Lindsley?

JASON: I do.

DAN: He will be on tonight. It will be a lot of fun.

JASON: That will be a good show.

DAN: Yeah. Okay, Elian is in Belgium. Pro streamer setting up the tease. So what makes good docs? First of all, I want to shout out to everyone who’s ever taught me about docs because I don’t have any original ideas. All I do is synthesize good ideas of other people. So Rachel Nabor taught me what good docs are. Silvia Vargas taught me what good docs are. The write the docs community taught me in general. I don’t have any original ideas on this. But that’s part of why I am who I am. I just repeat people who know what the good ideas are. I highly recommend anyone who wants a shortcut to success to just do that. So the basic answer to this question, the way I approach it, is it’s the same thing that makes a good product makes good docs. One of the things that Rachel taught us is that docs are the product. You should approach it as a product manager, not as a writer. That means that you need to understand your users and your audience. You need to understand what you’re building and the scope of it. You need to have a good relationship with the engineers and the designers, both behind the product you’re documenting and mind the docs itself. So if your docs are user focused, you’re probably writing good docs.

JASON: That’s — so that’s a really good point. And I think it’s a very good point that I would also say gets oversimplified sometimes. Because writing for your user is — you say that and everybody goes, yes, of course. Then you start writing, and you have to decide who is the user. Because one of the major challenges of writing software is that you can write something that is useful to a beginner and is useful to a very senior dev, and the documentation that those two people need is very different, right. So how do you create documentation that can serve the range of users without becoming that — what I would consider to be the accidental useless doc that tried to appeal to everyone and managed to lose everybody along the way?

DAN: Yeah. One of my rules of thumb for docs is you don’t want to be describing anything. You want to be teaching. And if we look at it through that lens, you have the same problem with teaching. Who’s in your classroom? You have this problem, I imagine, when you make content. Who’s watching? If you knew that the only people watching one of your videos were going to be beginners, that would help you so much. You would know exactly what to say and at what level to teach it. But you don’t. And that’s really hard. It’s a hard problem. One of the things that folks like Theo get to do is control the funnel. He does get to determine who his viewers are, and he actually deliberately re-directs other kind of people away. But we don’t do that in docs because the goal of docs is to be the core explanation, the core education product. We don’t scare people away from the docs. I know docs that, do but we don’t do that. Not in my philosophy. So what we have to do instead is create different learning paths for different people, different pieces of content for different people, even within one piece of content sometimes we hedge a bit and say, you know what, this section is a little advanced, but the way we position it within the docs is going to be okay for beginners. We hedge a little bit. Shout out to lots of cool — more cool people in chat. Matt Pocock, I have your course. It’s terrible. Just kidding.

JASON: (Laughter)

DAN: We got Alexis here. Alexis is a really cool person too. We’ve got Josh Goldberg, open-source extraordinaire. I’m Josh’s highest sponsor, and I don’t make that much money. So we need to fix this. Everyone go sponsor Josh on GitHub sponsors. Sorry, Matt. You need to learn how to educate people a little better. I don’t know. I don’t know what’s happened to you since the X date days, but you got a lot worse over time. Matt says buy Josh’s book. This is Josh’s book “Learning TypeScript.” Josh is not paying me to shill his book. I pay Josh to shill his book. That’s how much I like Josh. So there we have it.

JASON: Josh, that needs to go on your brag wall.

DAN: Yeah, user focused anything is hard, but user focused docs is especially hard because you cannot control the funnel.

JASON: Yeah, I think that’s sort of the major issue. I have been involved in docs. I’ve never been the person involved in writing docs. But when I was at Gatsby, this was one of the big wins of Gatsby early days, that the docs were really, really good for onboarding beginners. That was a big factor.

DAN: I remember that.

JASON: I think that’s why we grew so quickly. As Gatsby got more adoption, it needed documentation that appealed to a wider range of use cases, to a wider range of skill sets. That was where it really started to get hairy because it’s like, okay, Gatsby is a tool for building for the web, and its major strength is that it integrates with a bunch of other things. So where’s the line between what we should be documenting and what we shouldn’t be documenting? And like how far back do we go? Are we going all the way back to explaining how computers work? Or are we, you know, going to actually go out and document other people’s services? Like if we have an integration with a CMS, are we documenting how to use that CMS? Do we just say go to their docs and figure out how to use it and come back and use this plug-in. Those are decisions that are really hard to make. I think they’re decisions that change as a product matures as well because it’s different people, it’s different sizes of audiences. There’s different things at stake. How have you found that to be — because you’re working on Astro, which has the same challenge.

DAN: Same problem.

JASON: Everything, really wide range of users. How are you making these decision?

DAN: First of all, chat is complaining about static noise. I don’t know about that.

JASON: I think that’s coming off of you, actually.

DAN: All right. What can I do to solve this? I can turn my gain down. I can use my shittier mic. Sorry. Am I allowed to curse on stream?

JASON: A little bit. Maybe take the gain down just a tad.

DAN: Okay. I turned the gain down. I don’t know if that helps or not.

JASON: It looks — levels look correct to me. How does that sound to everybody, chat? Definitely cursed on stream like a degenerate. That’s right. Dom gets a pass because he’s from Philadelphia. There’s only so much you can do with a Philly boy.

DAN: All right. Chat says it’s better. There’s a hilarious flowchart. There’s a book called “The Docs is Product” or something. There’s a flowchart like trying to scope out all the different possible situations and answer the question “do I include this or do I not.” So it’s like — for example, if you’re integrating with a third party, does the third party already have docs on you? Does the third party matter to your users as like an essential part of the product? Does the third party — is the third party, like, willing to work with you? That’s a big factor, right? All of these things in this giant flowchart. It’s so silly. It’s the most corporate thing ever. The real answer to that is case by case.

JASON: Right.

DAN: But you actually gave two questions there. One is one do you do with pre-reqs? You mentioned the beginner stuff. What do you do with things that the user probably needs to know to use your product but are not part of your product? Like JavaScript. Gatsby did not invent JavaScript as much as I’m sure they’d like to have. And therefore, we need to figure out how to approach a user who is very new to web development and still wants to use Gatsby. So that’s a separate question to like Gatsby integrated with X, Astro integrates with Y, how do we teach that? And all that. I think different people will have different answers. I think Sarah’s approach — Sarah is the docs lead at Astro. Sarah’s approach is, yeah, put a line in the sand. Make it really clear. We have a lot of different answers to the different versions of this question. For example, for beginner stuff, we have a beginner tutorial that teaches you Git. It actually teaches you Git. It teaches you how to deploy to Netlify. It teaches you how to install the VSCode extension. And it doesn’t really teach you JavaScript, but that’s because the level of JavaScript used in the tutorial is so low. So you can really see us making a decision there. Yeah, we’re going to teach you everything you need if you’re a beginner to get something up and running because no real Astro user should be using Astro without Git. Almost every Astro user wants to deploy their site somewhere. So we’re going to include that in the tutorial. When it comes to partners, integrations, whatever, we have what we call recipes. There are different pages of recipes. One of the pages is for CMSs that integrate with Astro. So anyone can do a PR there and add their CMS. We’ve got a page for the deployments, all the different deployment guides, which oh, my god, there are so many ways to deploy an Astro site.

JASON: Right.

DAN: So yeah, we’re doing that. But then what happens to partners who — like people who are either partnered with the Astro company or are otherwise, you know, companies that are interested in working with us? But they don’t want to write a doc. They want to write a fancy blog post. Where does that go? Even trickier, what happens when they do want to write the docs, but their docs suck? What do we do now? That is a really tricky thing we’ve had to figure out.

JASON: Yeah.

DAN: All right. I’ve just blabbered on.

JASON: No, no. But these are all really good points. It goes to illustrate that, like, there’s more to documentation than just write down what it does. You’re not — it’s not ever that simple when you get beyond a fairly straightforward library. Because you’re now starting to look at, like, people don’t use this all the same way. Somebody can be using Astro to be building a marketing site, or they can be using it to build an e-commerce platform or they can be using it to write markdown or they can be pulling stuff from Contentful or Sanity. Those use cases are all very similar and a lot of the same things will apply, but there are a lot of corners that don’t line up when you start looking at these different use cases. So as someone writing docs and thinking through how somebody is going to interact with your software, you can’t just assume that one size fits all. You have to start taking all these variables into account. And because you’re integrating with third-party systems, you’ve got these challenges where third-party tools are maintained to higher or lower degrees of quality. You don’t have any control over that. You don’t work for them. You can’t make decisions about hiring or firing. If their CEO insists on writing the docs and it reads like a doctorate thesis, you don’t get a choice in that. So you can choose to completely re-write their docs on your own site, which means you have to keep up with all their development. So that doesn’t scale at all. So it just becomes this very, very complicated — like you said, it does kind of require a decision tree. You need to have a really clear set of expectations, both for what you can reasonably handle. Like how many pages of docs can a two or three-person team maintain and keep healthy? Once you know what that limit is, you kind of have to stick in it or else you’re going to end up with the problem that a lot of docs — like a big pain point I feel — I’m not picking on them because I don’t like them, but AWS is a pretty classic example of having rough docs.

DAN: I also have examples. Mine is Code Mirror. Sorry, Code Mirror.

JASON: But you can tell that what happened is somebody spent a lot of time to write that doc, and then didn’t have time to maintain it. So the thing moved forward, and it aged out. Now the doc isn’t relevant anymore, but nobody has time to go back and maintain it. So you kind of go in these doc dives where you’re trying to solve a problem. You get to the first doc, which is current, and then as you start to dig deeper, you find progressively more and more out of date documentation until it’s not useful anymore. And you just find yourself going on stack overflow for the one person who’s read the whole source code and can explain it to you.

DAN: A lot of people try to get into docs by writing technical blog posts. It doesn’t quite get there. Why? Because you don’t have to re-write your technical blog post every week.

JASON: Right.

DAN: So they get some, I guess, practice writing, but they don’t get practice maintaining. That’s the biggest thing about docs. It’s the biggest difference between docs writing and any other kind of writing. I’m a songwriter, but I don’t have to re-write my song if my audience changes. It’s the same song. I’m not going to redo it. Maintenance is, what, 80% of what we do, maybe? Maybe less. 60%? I don’t know. It also depends on what your role is on the team. I tend to do more writings than Sarah does these days. Oh, my god. So many great questions in the chat.

JASON: There’s excellent questions in the chat.

DAN: I’m going to do a couple shout outs. Good docs combined with simplicity and well-thought-out systems works. Good docs is going to complete that picture. Writing a bot for Astro support squad. Yes. You have an amazing bot. So excited about it. I helped set it up. I can 100% say that Astro docs are at least two to three times better than the docs for Algolia. Dave uses the compound noun Ryan-docs.

JASON: I’m assuming those are Ryan Carniato docs. Is that a correct assumption?

DAN: Yes, that’s correct. Ryan-docs have a lot of pros and a lot of cons. And we can get into that later if you want. What else do we got here? AWS. So actually, Rachel and I worked at AWS Amplify. I know that’s a little different than the rest of AWS. Any tips for internal docs? Yes, but it’s also a little less what I do.

JASON: And I feel like this is what we’re going to get into when we start working later. Because we’re going to be documenting something that I’ve built that’s basically for me. I’m not a solo team, but it’s a very small dev team. So we’ll be talking about some of the strategies there. So hang tight. We’ll get to it.

DAN: Ignoring issues is 80% of open-source work. Actually, part of the beauty and the uniqueness of the Astro docs team is we do not ignore issues. It’s a lot of work, but we don’t ignore issues. We don’t ignore PRs. Chrissy says that Free Code Camp makes you rewrite your blog posts.

JASON: This is a big challenge because I know when we — like when I was at Netlify, one of the things we had to choose was when we had a feature update, which blog posts of the hundreds of blog posts on the Netlify blog were valuable enough, referenced enough to go back and actually do updates on. And the list was pretty small. For every hundred articles you write, you’ll be lucky if one or two gets long-term traction. But you do have to pay attention to that because if — like, we have one on Netlify that gets really high traffic consistently. It’s one of the top visited sites from Google search every month. And it has to do with deployment. So whenever we make any updates to our deployment, we need to go fix that article. Because it’s effectively docs at this point, in terms of how often it’s referenced. But a feature announcement blog post, it’s getting no traffic, right? So going back to update it doesn’t matter. The docs themselves, though, it doesn’t matter if they’re low traffic. That’s your official stance on something. Even if it’s only getting a couple does hits, those couple dozen people, if they go and try it and it doesn’t work, they’ve now lost all trust in your product.

DAN: Yes.

JASON: I know as a dev I don’t necessarily trust a two-year-old blog post, but I should be able to trust every piece of documentation I find that’s considered official documentation. And I think that’s the difference.

DAN: Yeah, absolutely. And it also relates to a question we got earlier that I didn’t answer, which is what do I mean when I say control the funnel. I basically mean this. Your docs — the users matter, but your docs are also their own product. You don’t get to control who shows up to your docs. You don’t get to say, like, my docs are only for X people. No, the whole point of docs is they’re for everyone. That means every page in your docs needs to be written as if anyone could read it, even if nobody actually does. So, yeah.

JASON: Yeah, absolutely. Okay. So let’s see. We are about 25 minutes in. Do we want to talk about anything else before we start actually working on some docs? I’m trying to thinking if there are any big points we didn’t cover. Chat, if you’ve got something that you want us to cover before we start working on an actual practical project, now is your chance.

DAN: I love everyone is talking about Ryan-docs.

JASON: So why don’t we talk about Ryan-docs for a second. For folks who are familiar with Ryan, they maybe know what that means. I have a suspicion as to what that means, but I don’t know for sure. So let’s talk a little bit about what those are.

DAN: Ryan writes like Ryan thinks. So Ryan thinks in a very technical and concise manner. And also a very interesting manner. So people like Ryan-docs because they’re like puzzles. They give you an insight into Ryan’s brain. If you read Ryan-docs and succeed — dev says you have to read them seven times to understand. If you do read them seven times to understand, you feel amazing because you understand what Ryan is thinking. And that’s an amazing feeling. So that’s why people like Ryan-docs. Why do people not like Ryan-docs? Because people are tired. People are coming to get a question answered. People are trying to write code. They’re not trying to get in Ryan’s head. They’re not trying to be like Ryan. So Ryan-docs are not docs. They’re Ryan — Ryan. They’re just Ryan.

JASON: It’s sort of like a direct download of consciousness as opposed to — like they’re written for Ryan.

DAN: Exactly. So my job is to turn Ryan-docs into docs or turn Ryan thoughts into docs. It’s an amazing opportunity for me, and I think it’s an opportunity that has changed my life, like to be able to do that for people. And Ryan is very gracious about this. Ryan knows that he doesn’t write to a common denominator. He also knows, and I’ve tried to tell him this, Ryan’s writing is part of his success. It’s not something he should change. When Ryan writes articles on dev.2, if he wrote them in another manner, they wouldn’t be as popular.

JASON: People learn in different ways, and the value of a particular type of writing is so drastically different depending on who you are. Like if somebody who has been writing code for years and years and years reads something that Ryan writes, it is a nuanced set of insights into a specific thing, reactivity or framework authorship or something like that. If somebody who is pretty early in their career reads something that Ryan writes, it’s going to be opaque because it’s too nuanced. But for someone who’s working on a framework for someone who is mired in this conversation about like should we be re-introducing signals or sticking with something else? Do we want this thing or that thing? You’re talking about the trade-offs of building frameworks. You need a Ryan-doc. You need people like Ryan who have that really deep understanding of why different frameworks made different choices and can speak to it from a historical standpoint, not from an I feel this is better standpoint. So we do need those. But we very much need someone to be able to take that and translate it down to people who aren’t elbow deep in this world of framework design, right. Because I, who don’t spend a lot of time in framework design — and I know enough, but I can’t really keep up with the origin story of Signals. I need something to kind of condense all of this discussion down into a like, here’s your 101 on signals. Here’s where they came from. Here’s why they’re interesting. Here’s how they’re different from what you’ve been using before. That, to me, you need those two layers of communication. In order for me to get to the point where I can read a Ryan-doc, I need to read a bunch of these 101 docs to build up enough baseline understanding to enter that conversation meaningfully.

DAN: Yeah, and this is tricky for me because a lot of the people in the Solid community, including myself, by the way, to a certain degree, were there because of Ryan-docs. For me, it was less about Ryan, the content he was writing, and more about his attitude as a very transparent framework designer. But a lot of people look at my work and they’re like, uh, sure. Why? Like, Ryan already explains it all. What do we need this stuff for? And that’s okay. I don’t need to be like always appreciated by everyone. The people who know what I’m doing, they understand it. Yeah, we got a shout out for Dan. I have a prepared rant I’ve given many, many times on Twitter spaces of analyzing Ryan, analyzing Dan, and comparing them. Because Dan Abramov has a similar problem from a different perspective. One day if I become Jason levels of dev-rel famous, I’m going to do a conference talk, a conference talk on this. I don’t know which conference is going to accept this talk, but one of them will because that will be my terms for showing up. I will give a conference talk on what we can learn from Dan Abramov and Ryan Carniato as writers.

JASON: Sounds like a heck of a YouTube video as well.

DAN: Maybe I’ll do the YouTube video first and that’ll get me into the conferences.

JASON: And there’s something really interesting to say about breaking down people’s communication styles. At the end of the day, everything that we’re creating is an attempt to transfer information from our brains to yours. So the way that I communicate and teach is very different from the way that Dan Abramov or any of those folks who are great teachers in their own way. Do you see how I subtly snuck myself into the group of great teachers?

DAN: Excellent.

JASON: But these folks — the way they think and the way they approach, somebody who learns really, really well from, say, Shaundai Person

DAN: I met her in person

JASON: She’s wonderful. She has these wonderful analogies. She tells you this real-world analog and you go, oh, I totally get that. For some people, that’s the only way you’re really going to understand this. And then Rachel Nabors or Julia Evans are doing these really visual descriptions of how things fit together and work. So for a visual learner, they’re going to love that. Ryan is off in esoteric, you know, the origins of thought kind of space. For people who think that way, they’re making new connections and really understanding things. All of these types of communication are necessary. And being able to dip into each of those worlds is really valuable. Even if you can’t necessarily write the way that Ryan writes or, you know, visually demonstrate a concept the way that Rachel can, you can still understand how those things work and how they’re effective, and that can start to give you clues as to why a thing you’re trying to communicate isn’t landing. Like if you’re having a conversation with a group and you’re saying it one way and they’re just not getting it, like my dad’s approach was always if you’re not understanding what I’m saying, I’m going to say it exactly the same way but louder. Right? And that never really worked. It was always very frustrating to me. He was frustrated that I wasn’t getting it. I was frustrated I wasn’t getting it. I was frustrated he wasn’t explaining it a different way. The best educators I’ve seen, they’ll try it. If they see that you’re stuck, they go, okay, let’s try a different tact. Then they’ll shift communication methods. So if they were trying to explain it in words, maybe they’ll grab a whiteboard and start diagramming. Then maybe they’ll use an analogy. You get these really wonderful moments of somebody being able to understand that problems are three-dimensional. My view point of it is how I’ve learned the thing. But if you start rotating it in your mind, you can see a lot of different ways to communicate the same information. By studying how great communicators do this, you can start to pull those tips and learn how to apply that yourself, even if it’s not your default, as like a back-up method or alternative method so you can create more and more educational, informative, consumable whatever. Blog posts, docs.

DAN: People will see me analyze writers, and they’ll be like, why? Why do you have so much to say about Dan Abramov’s writing style? Why the fuck do you care? That’s why.

JASON: Yeah, yeah. Exactly that.

DAN: Let’s dive into it.

JASON: Yeah, let’s do a little bit of practical application here. What I’m going to do is switch us over into — let me get into — wait. What screen am I in? This one. Then I’m going to move us into pair programming mode. I’m going to start by giving a quick shout out to Rachel and White Coat Captioning, who’s here doing the live captions for us. There is a closed caption button here on the video player, if you want to, you know, watch those, read those. And that’s made possible through the support of our sponsors. We’ve got Netlify, Nx, New Relic and Pluralsight all kicking in to make this show more accessible to more people, which I very much appreciate. We’re talking today to Dan, who’s on the old tweeter.

DAN: I tweet too much, and I tweet terribly. I’ve gotten so many messages.

JASON: Appropriate use of Twitter.

DAN: I’ve gotten so many messages from mentors who are telling me to shut the — up and stop tweeting. I’ve wrecked my own reputation by doing a lot of memes and shit re-tweets.

JASON: There’s no right way to use Twitter. There are some wrong ways to use Twitter, but I don’t think there’s a right way. As long as you’re having fun and not punching down, you’re using Twitter properly.

DAN: I punch up a lot, and it drives people nuts.

JASON: I mean, it’s really your call. You can choose how you want to do that. I am a no-punching social media user. Some people want to punch up. I think that’s good. You need to challenge people who are established, or else we all get too comfortable and start getting lazy. Again, it should be about having fun, not about doing it right or following a rulebook.

DAN: I tweet like I still have 500 followers, and I am at a point now that it’s different.

JASON: It does definitely change as you kind of grow in the number of eyeballs on your stuff. Because it crosses over into a point where something that would have been punching up at 500 followers is punching down at 20,000 followers. And if your not paying out to that growth and to your sphere of influence, there’s a big — there’s like this moment where it inverts and suddenly you’re a bully instead of somebody speaking truth to power or whatever you’re trying to do.

DAN: And 3,000 is not 10,000 or 20,000. It is quite small. However, it’s big enough that people who are publicly friends with me are at risk if I do something really stupid. And that is what I’m dealing with now. I get messages saying, hey, someone who doesn’t know you but knows me DMed me asked me what’s up with this Dan guy. That’s not a burden I want to put on my friends.

JASON: Yeah, that can be a challenge. Okay. So go follow Dan on Twitter. I guess follow his emotional journey as he learns how to use Twitter as a large account.

DAN: Exactly.

JASON: You had sent me this tweet specifically. So I’m going to put this up on screen and let you talk about it.

DAN: Yeah, so this is the announcement we made about a couple weeks ago that I’m coming back to lead the Solid docs project. So for a long time, I took a break. I was doing some other stuff. I made videos, conference talks, but I wasn’t leading the docs. Yeah, things have been a little rockier the past couple weeks. I started a job search at the same time as this announcement. But in general, I’ve been streaming, actually, on Twitch, starting this new docs project effort. It’s very, very exciting. I’m coming back to the docs project. It’s different. I’ve learned so much over the past year from Sarah and from Astro in general and also just from new connections I’ve made in the open-source ecosystem. I really am trying to take all of those learnings, put them together, and create an amazing project. I did a kick-off call with Rachel about this new project. They gave me some amazing advice. I’m incorporating that. We shouted out Silvia Vargas. She’s a mentor who’s so fucking patient with me. I’m a bad person to mentor because of how publicly stupid I am. But she, time and time again, I will do something that’s disrespectful, and she’ll time and time again coach me and help me put the pieces back together. But she’s also an incredibly good advisor on a sentence-to-sentence level. So I’m taking what I learned from her last time around and applying it from the get-go this time around. She taught me things like how do you write for someone who’s tired, that your writing is accessible to someone where their first language isn’t English. How do you deal with different wordings and stuff like that? So I’m learning from her there. Obviously, I’m learning from Sarah in terms of community management, in terms of scoping, all that. I literally made my career off taking things these people have told me and trying to make them happen. The Solid docs is going to be the fruit of that, I hope.

JASON: That’s great. Well, cool. That’s super exciting. And so let’s put this all — you know, we’ve been talking in the abstract. So I’m going to give us a real project here. I’ve been working on this rebuild of the Learn With Jason site. I’m on this branch that is so poorly named because it started as an experiment to use Zod to type my APIs and turned into a complete rebuild of the entire Learn With Jason galaxy of sites. I never renamed the branch. So what I’ve got as part of it is I abstracted my API out into its own independently deployed site. As you can see, I don’t even have a readme on this. So I’ve built out all these end points, some of which aren’t public, like the Shopify stuff is just for me. But a lot of this stuff is public. If somebody wants to build a demo and use episodes of my show, they can do that. This API is there for folks to use or if they want to pull a specific episode or featured episodes or if they want to get a poster for one of the shows. All those things are done in a way that is intended to be usable by other people, mostly as an educational thing. I don’t know who would be building anything for Learn With Jason. But if you need API data, this is an open API that doesn’t require auth and is course friendly so you can try it out. So I don’t have any way right now of telling people how to use this. I don’t know that I tell people it exists, outside of moments like these where I mention it on stream. So if I want to document this, what should I do?

DAN: Yeah, cool. First of all, I want to say hey, core. People say core solves some fundamental problem with the web. I think the people who designed the web screwed up somewhere and I hate cores. But anyway, in order to approach this project, we first need to figure out who the users of the project are. Then we can figure out how we structured doc. You mentioned a couple things there. People can use this as a playground for their own projects. I’ll just query the Jason end point and grab his episodes and put them in a React list or something. But then also, I’m going to assume — like, I don’t know how big your team is. Let’s say your team grows. You need to make sure everyone on your team knows how to query the API, the internal API. That means things like Shopify get cart should be documented. If you were telling me no, no, no, that’s really just for me, I don’t want anyone to use it, I would still document it.

JASON: I mean, honestly, even if I’m just documenting so I can remember how it works. If you told me I needed to make a change to this, I have to open the code and look at it and figure out what I did. I truly don’t remember.

DAN: Yeah, so the nice thing about having just an API is using an API fits with an existing knowledge base, an existing paradigm. For example, when we were talking about for Gatsby things that you — like you didn’t teach people how to use JavaScript. When you’re documenting an API, you don’t have to teach people how to use Curl or Rest or whatever. It’s nice to have a Curl example, but you don’t have to teach what Curl is.

JASON: Right.

DAN: So that’s a big leg up for you. You’re probably not going to spend a lot of time in the tutorial sphere. Can you go to a website for me? Diataxis.

JASON: Like this?

DAN: Oh, use Arc 2. Love it. So click on that. When people ask me, like, I’m new to docs, what’s your number one resource? It’s just this website. It’s a pretty simple documentation framework. The idea is we split content types into four quadrants. Have you seen this before?

JASON: I have. So Rachel, on the Netlify team — let me pull up her stuff. Let’s see. There she is. So this is Rachel, who’s the docs lead at Netlify.

DAN: Oh, she just added me on Twitter. I was like, I don’t know who you are, but it says — what did it say? Information developer at Netlify. I was like, okay, we’re friends. Yay.

JASON: For many reasons, but one of my favorite things about Rachel is that Rachel also does musical stuff. So at the Netlify all-hands, before I left, she did a whole thing about deploying to Netlify sung to the tune of “You’re Still The One” by Shania Twain. She just got up with her guitar and sang it.

DAN: Fun fact, I’m a singer/songwriter, so we would be friends.

JASON: Perfect. All right. You know the musician to tech pipeline is strong.

DAN: It is so strong. I actually went from tech to music, but that’s another — a story for another stream.

JASON: Oh, all right.

DAN: Okay. So the basic idea behind this framework is you have four types of content. If you design around these four types of content, it’s a good — what do you want to call it — a good heuristic for if you follow this framework, you probably have decent docs. Or at least user-focused docs. So the four categories are tutorials, which are I’m going to teach you how to use a thing by doing something, and the something we do does not have to be particularly useful to you. The number-one goal of a tutorial is to be pedagogical. It’s to be effective in teaching the concepts. If you throw out the project that you make in a tutorial and you cry, you’re missing the point of the tutorial. Now, a lot of tutorials happen to be useful things. Like the Astro blog tutorial is useful. You get a blog. But it doesn’t have to be that way. Then we have how-to guides, which are similar to tutorials in that they’re instructional. They’re step by step, just like tutorials. But they’re different in that they are specific. They are task-oriented versus learning-oriented. You come to a how-do guide wanting to know a specific thing, wanting to accomplish a specific task. How do I deploy Gatsby to Netlify? That’s one task.

JASON: So to kind of frame this with two different questions. If I’m saying how do I use Astro, I’m looking for an Astro tutorial. If I’m saying how do I load Contentful data into Astro, I’m looking for a how-to guide.

DAN: Exactly. And that’s why we have two sections in the docs, tutorials and recipes. Then we have the bottom half, which is explanation. So explanation is —

JASON: This is where a Ryan-doc would fall, right?

DAN: Exactly. Another example is like Dan Abramov’s writing. 90% is that category. Even if you look at his docs writing — for example, I don’t know if you’ve seen I think it’s called “don’t use, use effect”.

JASON: Why you might not need an effect.

DAN: Yeah, that’s this quadrant. He’s not doing a tutorial. He’s not telling you how to accomplish a specific thing. We’re going to get to reference, but he’s not giving you a reference you look up. He’s doing an understanding-oriented page all about getting your head where his head is at. So explanation is, yeah, where Dan and Ryan live. Then the last quadrant is information-oriented reference, which is less about deep understanding and more about surface-level confidence and comprehensiveness. So if your explanation docs are not comprehensive, in other words you only explain certain hard things, you’re okay. If your API reference is not comprehensive, you’re screwed. Like you need to document everything for this last quadrant.

JASON: Okay. So here’s a question. This is going to be heavily opinion based. So anybody taking notes, add a big old asterisk for caveats here. If you are a team of one or two and you’re tasked with documenting something, which quadrants are non-optional? Where do you start? What should the distribution be when you are trying to document something if you want to make it as good as possible given highly constrained resources?

DAN: I feel like — I promise you I did not feed you this question. I just had to make this decision for Solid docs. One of the things I’m doing this time around is scoping the project. So I’m like dedicating two, maybe three months to it, and then we re-evaluate. So I had to look at my previous plan, which is very ambitious, all four quadrant, and cut a lot of stuff. So I cut — for Solid docs — basically, my answer is it’s circumstantial. It depends on your users, what your project is. So for Solid docs, I cut the two top and am focusing on the bottom two.

JASON: Okay.

DAN: Why? Because I actually already wrote a beginner tutorial, and that tutorial is good enough to have a beginner Solid tutorial. It’s not the best. Ideally, I would rewrite it and add another tutorial as well. But it’s good enough that I’m fine with it. How-to guides are covered by the community now. So even if I don’t write a Solid Jest guide — it happens to be we have a contributor, Michael, who actually is putting that in the docs. But even if he didn’t, someone would have some dev.2 posts out there that’s how to use Solid with Jest. That was good enough for me to cut it.

JASON: Okay. So you just said something that I think is really important, which is a very big qualifier to why you were able to make the decision that you made. Solid has an active enough community that how-to guides are being generated for you.

DAN: Exactly.

JASON: My gut would have been if I am a team of one, this is the side of the matrix I’m on. Like, I’m going to be writing reference and how to. And I’m going to let this stuff wait because we might not have an end-to-end tutorial, and I don’t necessarily need to explain why things work just yet. I first just need to make sure you can do stuff.

DAN: Yeah, it’s so circumstantial. I agree with you, sometimes. For example, I’m talking to a company that would be hiring me as a team of one, and I wouldn’t do — you know, given their situation, which is new product, no existing community really, like a very small one, alpha product, I would actually cut how-to guides and do tutorials and reference as my two, if I could choose.

JASON: Here.

DAN: Yeah, those two. Because for them, they need to grow their community. And having a good tutorial is key to growing a community. Whereas how-to guides are not only a little less important for growing a community, but when you have an alpha product, how-to guides are going to change a lot. And you might say, like, oh, reference is going to change a lot too. I would say, yes, it’s going to be a very intensive process to maintain reference for them, but it’s going to be so important because when you have an alpha product, you need to make sure that you are always updating your docs so people know where things are at.

JASON: And an important caveat, too, is that maintaining a reference doc — because, like you said, it’s surface level. It’s just facts. This is the API. These are the arguments. This is what it returns. It’s very different from a how-to guide, where if they change an API, you’ve got to re-write the entire thing because one core functionality just changed, and now you have to rip out the demo and do it again. So the maintenance is high on both of these, but the intensity, I think, would be much lower on reference than how-to guide, depending on the footprint. If you have, you know, hundreds of references and like two how-to guides, that clearly doesn’t balance out. But an equivalent number of reference guides and how-to guides, it’s going to be easier to keep the reference up to date given the shallowness of a reference.

DAN: Especially because part of the maintenance of reference is automated.

JASON: Oh, yeah. Because you can put like open API or GraphQL introspection or something like that on it.

DAN: Yeah, depending on the product, you’ll have some automated approach. Obviously, I don’t recommend just leaving the auto generated thing as the entire docs. But I’m saying in terms of maintenance, it’s automated that you need to update this with this new interface. And that makes it a lot easier to maintain reference. For example, the Astro reference, most of it is automated in that way. Obviously, changing the code doesn’t write docs, but changing the code changes the interface of the thing. Then making sure we update the actual description. Actually, it’s all tied together so that when you — when you’re in the VSCode editor and you get the, what’s it called, the context menu thing, it’s the same content you would find in the docs.

JASON: Oh, cool. Okay.

DAN: Okay. Anyway, the reason I brought this up is in your case, what would I do? I would choose the — basically what you said, the two things on the right. The how-to guides and the reference. Because you’re not like a framework or a product, the tutorials thing is a little — like, what exactly would we be teaching? We would just be teaching stuff in the reference. It’s not that important. Then explanation, no offense to you, but you did not introduce any fundamentally new idea. So we don’t need to do that. So this is actually a pretty simple choice that we’re going to start with the bottom right quadrant and move to the top-right quadrant.

JASON: Right. Okay. So that makes sense. So let me open — we’ll open up code. And I opened it in the wrong window. Let me switch.

DAN: Yeah, this is a good opportunity for me to talk about readmes versus docs sites. If your project is this small, I don’t recommend having a docs site. It’s just going to be a maintenance burden.

JASON: No docs site. Okay. So go with the readme.

DAN: Go with the readme, yeah. You can even — the cool thing about readmes is — people are saying I have echo on my side. I’ve tried to fix this. I don’t know what to do.

JASON: I’m not getting the echo. I wonder what’s going on.

DAN: Yeah, one of the cool things you can do with readmes is if your project is a mono repo or has multiple folders, you can put readmes in the sub folders. Then your main readme links to the sub readmes.

JASON: Okay. Okay. Did that echo drop out just now? I just realized there was another mic source active. Okay. We’re going to roll. Let us know if it gets better or worse. Okay. So I was looking at audio settings and not listening to you. So please say that one more time.

DAN: Oh, I was saying that a cool thing you do with readmes, if you have sub folders or a mono repo, have lots of readmes. Your main readme is the entry point to all the other readmes. It basically turns it into a docs site.

JASON: Cool. I can get around that.

DAN: We’re not going to be able to do a lot of sentence writing, probably just a bunch of outlines. The first thing we want to do in the root readme is define what the product is and why you want to use it. Oh, you might already is that.

JASON: Well, this is the mono repo readme. It’s just kind of a big dump of —

DAN: Oh, now we have another problem.

JASON: Look, I did a little bit of stuff.

DAN: Oh, you already did it, yeah.

JASON: Let’s pretend I didn’t and just go in here.

DAN: I can only sort of make out the text. Like on the right, it’s all blurry.

JASON: Oh, let me make that bigger then.

DAN: It’s just a little pixelated. It’ll be fine. You already started documenting stuff. So let’s look at that again.

JASON: Okay. So this is my core readme here. This is all kind of top stuff. Then we can drop into here. This is my catalog, upcoming schedule. It’s currently built in a combination of Remix and Astro, moving toward an Astro-only build now. I use Netlify functions for everything. The backend is powered by Sanity and Shopify and Markdown. Then I have an Algolia search. So I have the API. This is it. This is the end point. This is what it does. So there’s no real clarity in what’s going on here. Also, I’ve only documented three end points. So there’s not a lot going on in here. This is basically, I think, me just putting the absolute bare minimum so I didn’t forget that, for example, I have this option to grab a transcript.

DAN: Okay. We got a good suggestion from chat that really fits with me. Let’s grab this readme and paste it into a HackMD. It’s like a Google Doc for Markdown. We use it internally on the Astro team.

JASON: I’ve never heard of this.

DAN: It’s really great. All you have to do is log in with GitHub or something, and you can generate a doc. Yeah, this is another point about docs, which is like you want to have a toolkit, a toolbelt or whatever for writing docs. Whether that’s maintenance or writing or whatever. So this is one of those ones. Cool. So now that it’s in here, hit share and put my email in there. Or everyone. Make it public. You’re going to have to give me write access, though.

JASON: Okay. So I’m going to copy this and throw this in so that y’all can see what’s going on. And then to share to you, I do that with — here. No.

DAN: Share and then write. There’s a dropdown. Actually, that should be fine. I’m a signed-in user. Maybe you have to put my name in. I’m pretty sure it’s just my email. My email is public.

JASON: What is it?

DAN: Danjutan@gmail.com.

JASON: There you are. Invite.

DAN: Oh, my god. We’re running out of time. I’m getting so anxious.

JASON: And write. I’m going to —

DAN: All right. Looks like I have edit privilege. Let’s test this out. I’m going to write some stuff on my side. Yep. Looks like I’m changing stuff on your side. So we should be good. All right. Okay. Now that we’re here, I have 30 minutes to impress you. What am I going to do?

JASON: You’re going to do great. You’ve already impressed me.

DAN: Cool. That means a lot. Okay. So this is a readme for both the site and the API that uses it. So we are going to change that by taking the API section and putting it in a new document. So what we’re going to do is use H1s to indicate different documents. So I’m just going to go up here and say this is the root readme.

JASON: Okay. Why didn’t that work? I broke it.

DAN: It’s good. It’s working.

JASON: Okay.

DAN: Then I’m going to do a new one. What’s your folder structure again?

JASON:/site/API.

DAN: We’re going to do /api/readme.md. Then we’re going to move this for now into there. Then we’re going to have a link. So we’re going to say if you want to load episodes or schedule, there is an API available. So I would rephrase that to — because you can load it using the website. It’s specifically programmatic.

JASON: So we can do —

DAN: Yeah, yeah. Exactly.

JASON: I will send somebody to — it was sites/api. I can just link to the root folder, right?

DAN: Yeah, yeah. If you’re in GitHub, I believe it will show the readme. So I would just say there’s an API available that serves —

JASON: I can wordsmith it later.

DAN: Okay, yeah. Sentence writing is hard to do quickly.

JASON: Yes.

DAN: So let’s just focus on structural stuff. Okay. All requests are made through the /api/v2 path. Perfect. So first we’re going to start off with an overall marketing header, effectively. Like Learn With Jason API. This API lets you da-da-da. I’m a bullet-list fanatic.

JASON: I love a bullet list.

DAN: When you’re writing, you can start by colon, then bullet list. Then you can evaluate, do I want to turn this into a paragraph, two paragraphs, keep it as a bullet list? All that.

JASON: I got you. So let’s see. This will let me load lists of episodes, load individual episodes, load episode posters. You can load shop products. You can load the schedule. You can — what else can we do here? Let’s look. We can also get featured episodes. And what else is happening? Load a list of show sponsors. Load a list of episodes by topic. And I’m going to — we can skip this part because there’s no way we’re going to have time to get to it.

DAN: Right, those sort of more internal ones. Cool. So this does two things for us. One is it lets us craft a really good introductory paragraph. So in other words, you listed a bunch of stuff. For an introductory paragraph, I wouldn’t list all these. I would say this API lets you load episodes, products, and schedule. Or episodes, products, schedule, and sponsors. But the other thing we have is now we have an outline. Now we know exactly what we need to put in the reference doc. So Dave says you’re creating an outline before filling in details. Yeah, we gave the food for an introductory paragraph, and we basically wrote a quick outline. Let me show you an example of this kind of writing that I’ve done. Let me just grab it. I’m going to stick it in Twitch chat.

JASON: Okay.

DAN: So if you check out this readme and bring it on screen, I basically did the same with how-to and reference. So yeah, just scroll down a bit. Wait, hang on. I’m watching the wrong screen. This is introductory material. This is a little bit of explanatory because routers are more tricky than Rest end points. Then we have a table of contents. If you look at it, some of it is how to and some is reference. I sort of combined the two. And then there’s reference at the end. This is a good example of the how-to/reference thing without them being two separate pages. So in terms of your system, you might want to do a similar thing where first you have how-tos of like accomplishing a basic task using your API. Then at the end, you just document every end point as a quick reference.

JASON: Yeah, I think we could — let’s do this. Let’s maybe think through our table of contents here. So we can go here. Wait. Here. If we go make a table of contents, and then down here.

DAN: Yeah, I love it.

JASON: So starting here, we would want to kind of have general usage. So the most recent episodes of Learn With Jason. We would want to get the upcoming schedule. We would want to display a poster of a Learn With Jason episode. Get a list of sponsors. And a list of store items. Then we would want our reference. And that’s where we get into, like, api/v2/episodes. And we can start running down the list here.

DAN: Cool.

JASON: Also, we’ll put the rest in.

DAN: Yeah, one thing to add here that’s always an interesting question is where do your types go? Do your types go in the reference section? Do they go before the how-to section? Do you teach them along the way? Types are really helpful in explaining how-to stuff. Like what does this end point return? But it also kind of reads reference-y. You don’t want to plop a TypeScript-y definition. Are you using Zod or TypeScript or both?

JASON: So this is part of my plan here. What I’ve been doing is taking each of these, like here. I have my types, right. So I built an actual types package where I’m able to share these between my frontend and backend. The nice thing is I’m able to use Zod then to get my product schema. Then when you look at the actual products here, we load out of Shopify, and then turn it into the product schema. Then in the page that actually references it, I can also import that as a type so that you get autocomplete on the page displaying it.

DAN: Cool. Can you go —

JASON: Yeah, we’ve got the types.

DAN: Go back to the schema.ts file. Let’s just — I want to see all the different schemas. That’s just a helper function at the top, right?

JASON: Yeah, so right now I have just my products in cart, but the intention is to eventually get all of these.

DAN: So episodes will have one too.

JASON: Yeah, this is still a work in progress, but there will be one for an episode, episodes, for the poster, all of that. So that people can get what’s in each of these schemas.

DAN: Yeah, so from my perspective, things are straightforward at this point. Like, I would not shove the schema above the how-to guides, and I wouldn’t describe the schema in detail yet. I would probably link to it. It depends. You don’t want people reading Zod. It’s very tricky. You rather people read the TypeScript output.

JASON: Yeah, that’s actually a good question. So Zod will let you export the type, right?

DAN: Yeah.

JASON: And the way that I did that was — did I do it in here? I think I get the type, and then somewhere in here, one of these, I’m like importing it and using the exported type as the — you know how you can do a Zod, whatever it is. You know, export type.

DAN: Yeah, I don’t even remember what it is.

JASON: But so once you’ve inferred that type — yeah, Zod infer. Thank you, TimeAnalyst. Then what would it take to just do the infer and then drop that into the docs so that it’s always in sync?

DAN: I think that — I really want an automated version of this. What we don’t want to do is copy/paste it and have it go out of date every five seconds.

JASON: Exactly. That was exactly what I was thinking of. Because I tweak this a lot because I’m learning.

DAN: Yeah. Now I’m also thinking about organizational structure. Maybe I would do — yeah, so we have this sort of how-to section. Then we have the reference. Then maybe at the beginning of the reference section we have the types. Types and then end points. I like that a lot. The how-to guides will sort of teach the types along the way. It’ll be like access to this property, whatever. I love where this is going because this happens all the time in docs. We end up in a spot where we need a tooling thing. Sometimes the tooling thing is like, oh, we really want to introduce asides, like little different colored boxes in the docs, but the docs thing we’re using doesn’t support that. We have to build it. Sometimes it’s like, oh, we need a special — like if you go to the Astro tutorial, it has a very special side bar that lets you navigate many pages more easily. And this is a good example on the reference side, which is oh, shoot, we should probably automate something before we create more work than we solve.

JASON: Right. And startupbuilder and Joshua are in the chat talking about the type annotations to generate code. Josh is asking — I haven’t used TypeDoc, have you?

DAN: No, but I don’t think that’ll help us here.

JASON: We’re going to need some kind of way of referencing the type we need and then almost kind of replacing it on build or something with the right stuff, which is going to be — I know exactly how I would do it, and I feel like it’s going to be gnarly. So I hope that somebody has already built this in a way that I — because what I would want to do is imagine, you know, we’ve got, what was it, product schema. So what I would want to do is have some kind of inline type. Then I would add — this formatting is getting wonky, but stick with me here. I would be able to do something like, I don’t know, we’re here and we go to packages, types, and then we get product schema. Something like this. From this, this would then be expanding into the TypeScript definition. So I would be looking for something like this that exists, where it kind of parses this import and does the rest for me. And that way it would stay in sync.

DAN: Yeah.

JASON: So this seems like something that somebody else has probably solved already. And if not, what a great open-source project for somebody who’s not me.

DAN: I think — Solid is not using Zod, but I want it for that too. Like when I go and — I’m going to do the reference stuff last because we already have it written out. But I would like it to have this solution where I can just import the — because again, it’s not enough to have something that pipes in the type. A lot of times you don’t write the type explicitly. In this case, we use Zod. In Solid’s case, it’s often inferred from the function. So this would help in either case, the ability to import and analyze the type. So yeah, cool product idea for someone to make. We got a question. Why all types before and then all endpoints? Instead, type 1 plus endpoint 1, type 2 plus endpoint 2. That’s fine. That’s a good suggestion. Instead of putting all the types before, you could do the episode schema and then the episode endpoints, the product schema, and the product endpoints. That would also be fine.

JASON: Yeah, you could do something like you’ve got your args. Then you would have episode args. Then response would be episodes. Right? And those would be the types. And then you would need to put some explanation in, but you could kind of interweave these. When I’m looking at an API reference, what I want to see is what do I pass to it and what do I get back. Have that done in some way that makes sense. And the nice thing about, you know, everybody switching to TypeScript is that we all kind of have a shared language for this stuff now. So being able to throw those in where I don’t actually have to explain what’s passed in, just here’s the type, does make life a little bit easier.

DAN: And the reason why I want to put the schema first is because multiple endpoints use the same schema. You don’t want to have to copy and paste it twice.

JASON: That’s a good point. So then what we can do is reference back up and say, you know — or you could put the types down below or whatever.

DAN: Yeah, whatever it is.

JASON: Then the endpoints say the argument is at episodes args. And that links to the definition. Then when episode and episodes both return an episode, because actually it’s probably more like this, then you can — you know that both of these are going to reference an episode, and we don’t have to double up on the types. I think that’s a good idea.

DAN: And look, not everyone uses TypeScript. So you have to figure out what you want. Do you want to document your thing from the perspective of someone who does not know how to read TypeScript? Or do you want to take that as a pre-req? Either way, there’s good approaches. If you don’t want to just shove a TypeScript type definition in front of someone, you can create a table that’s a little bit kinder about how it portrays types. Yeah, so this is interesting. The example request, example response, you don’t need this to overlap with what you did over here. That’s also why I was going to ask you about the how-tos. The more the how-tos combine multiple endpoints to accomplish a specific goal, the better the how-to guides are going to be. But it might be —

JASON: Then in that case, maybe it’s just that I don’t need them.

DAN: Yeah, you might not actually need them.

JASON: The how-to is here. This is the how-to.

DAN: Exactly.

JASON: I don’t really combine my APIs. I kind of built each one for a specific purpose. And I don’t really like API request chains. So I tend to try to figure out a way to make it a single API for whatever I need.

DAN: Yeah, and I hope people view this as instructive. Documentation frameworks are there to help you at the top end. They’re there to give you a framework for everything that could possibly need. But your project doesn’t need everything. Your project has its own needs. Even if your project is big, sometimes you don’t want to just take the docs framework as it is. You want to deviate from it a bit. In this case, we looked at it and were like, you know what, portraying all the information as part of endpoints makes a lot more sense than doing dedicated how-to guides because the how-to guides aren’t really adding anything additional to it. We talked about some of the great examples of how-to guides, like how to use Astro with Contentful. How to — in my router doc, we have, you know, how to do nested routes or whatever. But here, it’s really the API is nice and well self-contained and well designed. Each endpoint corresponds to one task.

JASON: Mm-hmm. Yeah. So I mean, there’s a lot of variability here and a lot of different — again, what problem are we trying to solve? Who is this for, and how do we expect people to use this? In my case, the APIs are intended to be used more or less standalone. You’re rarely going to be combining them. And therefore, it doesn’t really make sense to make separate how-to guides because the example request and response is sufficient explanation of what’s going to happen.

DAN: Yeah, exactly.

JASON: And so that’s less to maintain. It’s also less to parse as a reader. You don’t have to jump around. You go to the endpoint, and the endpoint explains everything it is, including usage. That’s actually my favorite kind of API doc when I’m dealing with something I’m pretty familiar with. With Shopify, I don’t want to open five docs to see how something works. I want them to show me all of it in one place.

DAN: This is especially true for APIs. It gets back to the point I said earlier. An API fits with something you already know. You already know what a Rest endpoint does. So you don’t need to have a tutorial that explains that and have that open alongside it. One thing I want to do and get your reaction is if I took this bit here, what do you think?

JASON: Oh, like to lead?

DAN: Lead by example.

JASON: Yeah, why not? I think that’s great. I think the ultimate goal is that somebody who’s learning would be able to use this as an API. I think one of the big challenges I run into is when I’m making demo, I’m always looking for APIs I can reference. There’s only so many times we can build a Pokémon app before we want to shake it up. So I think it’s cool for people who make content, like open up an API so other folks can make different types of apps. You know, you can’t really make a podcast-style app demo using the Pokémon API, but you could using my API. I think maybe Syntax has an API or an RSS feed you could use. All those are ways to just allow people more fun ways to build and experiment as they’re learning. Because yeah, there’s not really a commercial use for my API. What are you going to do with my API, right? Other than learn. But it’s nice. It’s nice to have one available if you want to play.

DAN: Yeah. So yeah, I’m satisfied with where we’re at with this. I like how we ran into a bunch of tooling problems. Another example is I would love that every time you edited the function signature inside one of these files, a PR would open to this, like with some comment at the right spot that you need to edit. That would be so cool.

JASON: Yeah, I mean, it’s stuff like this that is — I want to go dig because it’s just really hard for me to imagine that somebody hasn’t already started tackling this problem.

DAN: It’s easy for me to imagine, though, because I haven’t seen it. (Laughter)

JASON: Yeah, I mean, maybe it’s not there. And so for anybody who’s looking to build something that would make a significant improvement in the open-source space, here’s a challenge for you. Find a way to sync up Markdown documentation with the declared types so that people don’t have to maintain in two places.

DAN: Yeah, I feel like I’m ending a job interview because I’ve been doing a lot of job interviews. And usually I’m like, all right, I’m satisfied. My questions are answered. Anymore questions for me?

JASON: Right. No, no, I think we’re in solid shape here. So we’ve got probably about five minutes before we need to wrap up. Chat, any questions for Dan before we wrap? Dan, any resources or other things that you think people should be aware of if they are going to go out and start documenting their own systems?

DAN: Yeah, we got Diastaxis.fr. We have Rachel’s episode on changelog. Oh, my god. There’s another episode coming out. Or already came out. Oh, wait. Is Rachel on it? I don’t know. Just look.

JASON: We have Rachel on two different things here.

DAN: The second one is the one that inspired me to do docs. But there’s a very new episode that I’m definitely going to go listen to. I’m very excited about this. What a discovery. The best — I did a tweet that had a list of people to follow. I recommend this approach. Rather than reading a bunch of books, follow a bunch of people. Then read their books if they come up. God, I’ll have to — do you know how to search Twitter? Because I don’t.

JASON: Yeah, yeah, yeah. What?

DAN: Do influencers. My only tweet that references the word “influencer.”

JASON: Let’s see if Twitter search still works.

DAN: There it is. I said want to be a better technical writer? Don’t follow influencers.

JASON: Watch. I just learned a thing. If I hit command, shift, C —

DAN: Yes!

JASON: It copied the URL.

DAN: I use that all the time.

JASON: I have like built this habit of opening up the address bar, right. It’s really nice not to have to do that. How cool is that?

DAN: Yeah, so go follow all these people on this list. There are so many — not bad actors, but docs grifters. In other words, people who write a ton of blog posts and think that they can give technical writing advice. No, you can give blog post writing advice. But you have no experience doing what I do. So I don’t want people — those people tend to be very, very high follower count because of their blog writing. But they’re not going to give you the best help you need if you want a career in technical writing. So I’m going to call those people docs grifters.

JASON: Yeah, it is important when you’re looking for advice. Like what do the people do who give the advice? And if their living it teaching people how to do the skill, then it’s suspect, as opposed to somebody who does the skill. That’s not to say that everybody who teaches, like teaches a thing, is necessarily a grifter. But it is — it should be a point of review.

DAN: Grifter — calling them docs grifters it something that would get people in my DMs saying, Dan, you need to shut up. But your point is the nuanced point they wanted to make. I’ve been on Twitter spaces where people are like, oh, yeah, I write an article every day, listen to me. I’m like, if you write an article every day, you’re not doing technical writing. I don’t know what you’re doing.

JASON: Mm, mm. Yeah, technical writing for documentation versus technical writing for tutorials versus like writing a think piece about the JavaScript environment, they’re all writing. They all involve tech. And they’re all three very different methods of communication. And so it’s definitely kind of going back to what we were talking about before. There are lots of ways to get information out of your brain and into somebody else’s. It’s important to remember that there’s a time and a place for different types of communication. Like, you don’t make a lot of jokes in docs for a reason. It doesn’t — like it takes somebody out of the learning. Whereas in a blog post, being funny is great. It can help humanize it and keep it engaging. So there’s a lot of subtle stuff that you just kind of learn by watching people who are really good at it. That’s why I think, back to your point, it’s important to follow and learn from people who are doing it because you get to see — you don’t just hear what they say. You get to see what they do. And that really makes a big impact on me. I think advancement beyond just the basic skills is often from like an apprenticeship model. Because a lot of us don’t get the opportunity to actually apprentice alongside these excellent creators, what really makes the value is watching what they release and then seeing why they made decisions the way they made them. So listening to somebody on a podcast, watching a show like this where you get to see people reason through why they would do something the way they do it, that’s that apprenticeship model. You’re not necessarily learning the core thing, like how to write a sentence. You’re learning the stuff that someone who does this for a living, what questions are they asking? What are they really paying attention to? How are they structuring their thought process to make better decisions about the end product they’re working toward? I think that’s how you really advance in a career. So yeah, this is a great list for anybody who wants to do more technical writing. And it’s worth kind of thinking about who are you looking to for advice in any field and kind of running through that same criteria. What are they building? What are they doing? Are they talking about the things they’re building, or are they talking about stuff they don’t do? But either way.

DAN: Chrissy is in the chat. She writes a blog post a day. I’m not talking about Chrissy. She doesn’t say, here’s how to be a writer. She just writes. And her writing is very good for blog post writing. I wrote my first personal blog post this week, and it was so hard. It’s not what I do. It was extremely hard. Whereas she would be able to knock four of those out in a week, I struggled to get one of them out. There’s nothing you do that’s problematic. It’s people who combine all the kinds of writing under one roof and say because I write blog posts, here’s how to write docs. But, yeah. Chrissy is amazing. Most tech writing roles I look at require links to content you created. Yeah, there’s a whole other discussion we would have in terms of how to get into the industry. Tech writing roles pay way less than they should. That’s a big problem. One of the reasons why I’m a PM, like I’ve worked as a PM instead a docs writer or docs lead, is because PMs get paid more. So.

JASON: Yeah, it’s true. But with that, we are unfortunately out of time. So I’m going to do one more shout out. Thank you so much to Rachel from White Coat Captioning who’s been doing the live captioning today. And thank you to the sponsors who make it possible. Netlify, Nx, New Relic, Pluralsight, all kicking in to make this show more accessible to more people. And while you’re checking things on the internet, go ahead and check out the — dang it. I did it again. Muscle memory. There we go. Here’s the upcoming schedule so that you can see what’s coming up. We have a new, fun episode next week. We’re going to be meta streaming where we’re going to be doing shaders in OBS. So we’re going to be messing with video streams and creative effects there. Lots of fun stuff about — like we’re going to have Wonder Graft. Please stay tuned. I think Silvia Vargas is going to come on the show. I’m talking to her about getting something booked.

DAN: On your show? That’s amazing. I finally booked a show with her. I think yours will come out first.

JASON: We’ll see. We’re still working on dates. Details to come. But really good run coming up this summer. I’m really excited as we keep running. And with that, Dan, thank you so much. Any parting words for the chat before we wrap this one up?

DAN: Yeah, just what Jason was saying before. What I’m trying to do right now is use my — like I was able to do all the apprenticeships, so I’m trying to figure out what I’m going to do to help the community who doesn’t get those apprenticeships, so if you have any ideas for me, tag me on Twitter. I’m doing a little content now. So let me know. What can I do to bring what I’ve learned from all these great people to everyone else?

JASON: Yeah, awesome. All right. Well, with that, we are going to go raid. So let’s go hang out with her. Thank you all so much for hanging out. It’s been a blast. We will see you next time.