Latest / The Not-Boring Tech Writer / Writing docs as an open source developer with Florian Lefebvre

Transcript

Writing docs as an open source developer with Florian Lefebvre · The Not-Boring Tech Writer

• Kate Mueller: [00:00:04] Welcome to The Not-Boring Tech Writer, a podcast sponsored by KnowledgeOwl. Together, we hear from other writers to explore writing concepts and strategies, deepen our tech writing skills, get inspired, and connect with our distinctly not-boring tech writing community. If you are passionate about documentation, you belong here. No matter your job title or experience level, welcome. [00:00:29] Hello my lovely, not-boring tech writers. Today I am delighted to introduce you to someone who's not a technical writer officially, Florian Lefebvre. Florian is a framework developer for Astro, which is a free open source framework, actually that I really love. I've built a couple little websites with it, so I was stoked when he submitted a suggest a guest request to come on. And as part of his role, he also writes documentation and reviews content from other docs contributors for accuracy, for all those fun technical details. So he's definitely someone who's working on documentation, even though he doesn't get the official tech writer job title. Florian, welcome to the pod. Florian Lefebvre: [00:01:14] Hi. Thanks for having me. It's great. Kate Mueller: [00:01:17] I'm so excited to have you here. I love talking to people who aren't official technical writers, because it's really exciting to talk to folks who are just excited to be working on documentation in any capacity. So before we delve into all of that, tell me a little bit about how you got into this field. What is your developer villain origin story? Florian Lefebvre: [00:01:38] So basically at the start of high school, I wanted to redo my orchestra's website, which was, which was basically very bad. So I watched a YouTube tutorial, I followed it, I didn't understand anything. It was a crappy result, but I loved it and looked like I stuck around, right? During all of high school, during the evenings, I was coding every day. I was obsessed with it. I got involved in open source quite early in various projects. I really like open source. And so yeah, after high school, I did start some university, but dropped out quickly because I knew too much, basically, it was just boring. No, honestly, it was a bit boring. I started freelancing really quickly. In the end, like I knew this open source project, Astro, I had used it as a user and from things to things, I started answering questions in the Discord and then in the end, I got invited to the core team. Kate Mueller: [00:02:50] Oh, that's so exciting. So it was just because you were active in the community, like initially because you'd use the tool. Then you started answering questions because you'd used the tool and you became part of the community and they invited you. Florian Lefebvre: [00:03:04] Yeah, that's really cool. Kate Mueller: [00:03:06] Yeah, it is really cool. It's a very natural progression and probably not something you set out to do originally, I'm guessing, you were just kind of there. So what does it mean to be on the core team and doing that framework development? What does that look like? Florian Lefebvre: [00:03:22] So just maybe that can help for the context. There are several roles, sorry, our governance, for example, there are maintainers who Astro recognizes your involvement in the community and so you have more rights. For example, you can merge some pull requests, this kind of stuff. And then above this, you have the core maintainer role where you have more, let's say, you decide on some of the new features, you have to review some bigger contributions from the community. You have the responsibility over some parts of Astro, like some specific features. For all of these things, it's not only code related. First of all, we have maintainers who have been only doing support like me at first, so it's not focused. There are many great contributions. Kate Mueller: [00:04:15] So for you, it was that you did support and then you kind of moved into the code side of it, it sounds like. Florian Lefebvre: [00:04:21] Exactly. I wasn't confident at first, but when I was invited to the maintainer role and then, I was like, oh, maybe I can actually understand what this code is doing. And yeah, a pretty natural path. Kate Mueller: [00:04:38] That describes my feeling about all code. I'm in the, “Oh, I don't really understand what this is doing, but I can maybe get it to work.” I have never progressed past that level. So you are definitely one up on me on that side. Florian Lefebvre: [00:04:50] And actually Astro is such a complex beast, like no one knows everything in this. Everyone has their own little area of expertise. But yeah, just getting the hang of one part of the code is enough to get started. Kate Mueller: [00:05:08] So what area of Astro do you work on? Is it a particular feature set or particular APIs, or, what is the area you're good at? Florian Lefebvre: [00:05:19] Actually, it depends. Like, for small fixes, it could be a bit anywhere really. I mean, there are some small fixes that are tricky, but for the easy ones, I mean, but otherwise I contributed two features to Astro. The first one is called Astro Env, which is allowing developers to manage their environment variables more easily, like to avoid leaking secrets on the client, for example, which is pretty bad. Kate Mueller: [00:05:45] Yes. Florian Lefebvre: [00:05:46] More recently, I worked on a fonts API to have optimized fonts on your Astro site, like getting funds from Google Fonts or Font Share or some providers, this kind of stuff. Kate Mueller: [00:05:57] Oh, nice. For those who aren't familiar, people do build docs sites with Astro. This is a thing. So for those of you doing maybe a docs as code approach, looking at new tooling, Astro might be a really good option since it is open source and free and it has a lot of really amazing functionality tucked in. I know for me, a big reason why I grabbed it was that I could use Tailwind really easily in it. And for me, that simplified my life a great deal. As somebody who is not a developer, I can say I did find it fairly easy to be like, “Ah, here's a theme template that I can tweak the way I want, and I can get a site stood up really quickly, really fairly easily.” Florian Lefebvre: [00:06:40] Yeah. The mental model is very easy for beginners. It's really pretty close to HTML. And also on the topic of docs, we have Starlight, which is a docs framework built on top of Astro. So it's really good, very performant. Many companies have been adopting it like Cloudflare and Netlify, for example, which have huge docs. So if you're looking for a framework, shameless plug, Starlight is great. Kate Mueller: [00:07:09] Hey, I like doing a little shameless plug. I mean, you're allowed to, to brag a little bit on the thing that you're building. I think you're allowed to do that. So that's a lot of what you're doing on the developer side. And there's a range of this, right? You're doing bug fixes, you're maybe doing some small feature work, but then you're also building whole big new features, right? And so what does that look like from the docs side of it? So, you're probably grouping bug fixes and stuff together, maybe in a changeset that goes out, maybe you're doing small improvements to a feature. How much of that do you handle documentation for? Florian Lefebvre: [00:07:50] So it depends. Like the famous answer, it depends. No. But seriously. For bug fixes, sorry. So we try to make changesets, like one changeset describes one thing. So if your fix or if you have a PR which fixes several things, we are not going to try to fix all of these things in one changeset because that kind of doesn't make sense. So it doesn't mean that every changeset has to be huge. It can be one sentence, one changeset, one fix basically. And it may result in a docs change if the fix for some reason, like while fixing it, you uncover that a behavior is not quite right or this kind of stuff. So it depends. Kate Mueller: [00:08:38] It does depend. I mean, it might be, "Oh, I fixed this thing, so it works as it should work" or "While I was fixing this thing, I discovered this other thing and I had to kind of fix both of them. And that combination actually changes some of the underlying behavior,” at which point you would need to document that in some fashion. Florian Lefebvre: [00:08:55] Right. Yeah, exactly. And sometimes you discover something, but maybe it's not worth documenting as well. There are some things we can't document. I mean, I don't have an example just like this, but if it's maybe a language feature or something, we can't document JavaScript on Astro, I mean, not all of it. So yeah, that's the bug fixing side. And then for small features, it's kind of the same like code. You code the thing, you do some tests, for example. Then you are going to write changesets to introduce the feature. It doesn't have to be huge, but just like, “Oh, here is this new feature, how you can enable it with a small code block.” And then there is an associated docs PR. Most of the time, I don't think there are many times where there is not an associated docs PR. And yeah, just adding maybe some things to the configuration reference or to a guide or in the docs there are several areas that could be touched by such a change. Kate Mueller: [00:09:56] And are you mostly at that point updating existing docs? Are you creating new docs? Is it another “it depends” situation? Florian Lefebvre: [00:10:08] Yeah, pretty much. But for small features, it's usually a matter of updating. You already have a big feature which has dedicated pages and you are going to add a section for example. Kate Mueller: [00:10:22] And now so, Florian, you came up on the freelancer side. Did you have to contribute to documentation in any of the previous roles that you had before you started the maintainer role at Astro? Florian Lefebvre: [00:10:38] No, never actually, because it was more on just doing a side thing. So no, no docs, really. Kate Mueller: [00:10:46] Okay. So Astro Docs was kind of your first docs experience. How did you feel about that when you started taking it on? Were you excited to do it? Were you intimidated by it? What were those feelings? Florian Lefebvre: [00:11:01] I don't know if I recall everything to be fair, but I think I was kind of lazy. I don't want to do docs, this kind of stuff. And yeah, also writing poor docs, that's for sure. I know my changesets kind of sucked at first. I wasn't very good at writing docs at first, and maybe I wasn't very enthusiastic about writing docs as well. Kate Mueller: [00:11:25] And how do you feel about it now? Are you less lazy about it now, more enthusiastic, or is it still like this thing you kind of have to do? Florian Lefebvre: [00:11:33] No, honestly, like today, I feel like making a feature is really code, tests, and docs, not necessarily in this order, but it's really a must have if you write some, if you create something and nobody knows it exists or how to use it, or if you wrote it so badly that no one can understand it, then your feature doesn't exist, basically. Kate Mueller: [00:11:56] Yeah, that's exactly true. I often use the phrase: "Docs or it didn't happen." You can build the most beautiful thing, add it into the product, but if nobody knows that it's there, it is as if you didn't build it. It's like the “If a tree falls in the forest and there's nobody around to hear it”, if you release an awesome feature, but there's no documentation on it, did you actually release the feature? I mean, you certainly did all the work to release the feature, but if nobody starts using it, it's as if you didn't create it. Florian Lefebvre: [00:12:28] Yeah. And also the fact that, I mean, we have such great docs, I want also the docs I write to be just as good for the people who are going to read it. And just because good docs mean happy users, also less support, for example, if the docs are clearer. This kind of stuff. Kate Mueller: [00:12:46] Yeah, I'd imagine, especially since you started doing some support, that you could feel the difference a little bit between things that were well documented and weren't well documented. I know I field more questions on stuff that I either wrote crappy docs on or didn't write docs on versus the stuff that I actually did write good docs on. I mean, you're always going to get some questions regardless of how good the documentation is, but if you have non-existent or bad docs, you get a lot more questions. Florian Lefebvre: [00:13:19] Yes. And I feel like I should have or pretty much always been very good. Like, even though lately there has been some work to update some reference pages that were old and a bit outdated. There is still some room for improvement. But yeah, I see the difference when I go to some other projects, maybe it's a niche project. But yeah, usually docs are such, it prevents you from using the tool because it's just not there. Kate Mueller: [00:13:50] Yeah, it definitely can if you've got poor documentation or no documentation, especially with open source things where somebody spun it up. People have put a lot of time into building the thing, but if nobody can quite figure out how to use it, or if it's going to take hours and hours of time to figure out how to use it, it kind of discourages you if you can find something else that has a really easy onboarding process, right? So the way that docs work at Astro, correct me if I'm wrong, you have a single person who's a docs lead who manages that process, right? Florian Lefebvre: [00:14:30] Yes, exactly. Kate Mueller: [00:14:31] Okay. All right. And so there is a maintainer who is a writer who's handling a lot of the intricate details. But then also the docs, like Astro, are open source, right? So anybody can contribute and submit PR's and the whole process. So she's likely managing docs PRs from maintainers or co-maintainers, but also probably from the community at large. Florian Lefebvre: [00:14:58] Yeah, definitely. There are all kinds of contributions. So in some ways the contributions from mainteners and co-maintainers are easier because they know what to do, like, what they are expected to do in a way, but it's harder because usually it's more involved stuff. So, you got something maybe complex and actually you have to untangle it to make it understandable, you know? But yeah, and then there are the community contributions that are some small contributions, some big ones. It really depends. But for the really new contributors, sometimes it's a bit challenging because you have to make them understand how you work, like, we don't put banners everywhere, like this kind of stuff. I mean, I'm joking, but it's a real thing. Usually when people contribute, they just have a big banner because they had a problem. And well, actually it could be a paragraph or something. So yeah, this kind of stuff. Kate Mueller: [00:15:59] Yes, the banners and callouts are one of those things that I think every documentation site has its own guidelines around, and it is often one of the things that contributors struggle the most with. It's like, I feel this should be a big blaring whatever. And you're like, no, it's not. I get that you think it should be because it was really painful for you. But we use them sparingly because we want them to have a lot of power. And this is not the thing we want everyone to look at on this page. Florian Lefebvre: [00:16:30] Yeah, exactly. Kate Mueller: [00:16:32] Or we don't want twenty of them on the page. Florian Lefebvre: [00:16:36] Yeah, we definitely have several banner PRs per week or per month, that's for sure. Kate Mueller: [00:16:42] I'm glad it's not just me. I'm glad that it exists for other people in the world too. It is that constant debate around how much do I call this out? Also, I know some people who have banner blindness, so anything in a banner they don't read. Florian Lefebvre: [00:16:54] That's a real thing, honestly. Kate Mueller: [00:16:56] It is. So you think you're doing a great thing to call something out, and then it turns out you put the most important piece of information in a field that like 20% of your readers won't actually read. It's exciting. Florian Lefebvre: [00:17:10] And maybe on this topic, we have the Astro Docs for Astro and we have Astro Docs Docs, or Astro Docs square, which are the docs for docs. And I mean, this is a goldmine, honestly. And we have a section on how to use specific components. And we have one for the banners or “aside” as we call them. And yeah, we document, okay. Usually we don't. You don't need the banner, but if you need one, this is the kind of banner you can use for this kind of use case. So what I mean is it's not just like, some people are like, “Oh, I don't like it, we have guidelines and this is why.” So it's also helpful to back us basically. Kate Mueller: [00:17:53] Yeah. I mean, it works both ways. It helps create that consistency across the docs site, which is a much better experience for everyone. But it also means that if you push back on a contributor's PR to be like, no, we don't do it this way, you can point to the guidelines and say, here, we officially don't do it this way. It's not like I'm just being difficult because I don't like you or something. There are official guidelines. Could you please follow the guidelines? And often it's just that people don't know they're there, you know, didn't reference them. And so some of it's just that learning process to get people to like, "Hey, we have docs about how to write docs. Can you go check those docs before you submit your PR?" Florian Lefebvre: [00:18:36] And yeah, to be honest, we don't just give them the link and say, go figure it out. It's more like, oh, we would do it like this. And then we just make a comment saying, "What if you did X instead of Y?" and let them figure it out a little bit. Not necessarily doing a suggestion or editing the PR. It's also part of the process to let them know how we work, how they can improve their contributions. It's actually super important too, I mean, people appreciate it. They want to do things right. Kate Mueller: [00:19:12] Yeah. If you've taken the time to make a contribution, you obviously care a bit about the thing that you're contributing to. And I think most of us, if we care enough to want to contribute, we want to be good contributors. And so teaching people a little bit how to be a good contributor, they've already expressed the interest, the willingness to take the time to create that PR. They're probably also open to a little constructive feedback so that their next PR might go out faster because it won't require that back and forth. And then they can actually see those contributions live, right? Florian Lefebvre: [00:19:50] Yup. And sometimes it happens that we edit the PR also, like sometimes they did some things, but the changes that are actually required are so different that sometimes it's a bit too hard. So we try to do it as much as we can. But then we have some calls which are called talking and doc-ing, and basically some docs stuff for two hours or three. Sometimes we pick a PR, we know that some changes are needed and we are going through what the initial contribution was, what it should be, how it goes. Like nit picking on the terms and this kind of stuff. And to get the perfect, at least, the best version we could do of this contribution that happens as well. Kate Mueller: [00:20:39] Yeah. The best version. That's a good way to put it. So you obviously make docs PRs for stuff that you are working on, but you also review some of those PRs, right, Florian? So some of the contributors, I'm guessing for things that maybe like the fonts API, if somebody submitted a docs PR relating to the fonts API, would you end up being one of the people who reviewed that because you built it? Florian Lefebvre: [00:21:05] Yeah, definitely, exactly. For the docs side of things, yeah, I would definitely review docs for things I am very comfortable with, things I built or things I'm using a lot, even as a user, for some other APIs that I didn't design, but I use it so much that I know it very well. So this kind of stuff I regularly get pinged to review. Or maybe reviewing an issue that happened a few days ago. Someone filed an issue saying, “Oh, I couldn't find this thing in the docs for viable funds.” And then we have to figure out what the best solution is so that I'm not going to submit the PR, maybe, like this kind of contribution. I could make the PR, but I mean, it's just an excuse to get the original poster (OP) to write the PR actually. So it's a great thing I think. So that's for the docs side of things. And then on the code side of things, because we have two repositories, one for Astro code and one for Astro Docs, then I can, apart from reviewing code, I can review changesets as well, to have maybe a good sentence or something that is more useful to the reader. Sometimes people tend to think that a changeset must describe what you did or the whole fix, but users don't care. What they care is what this is actually fixing, not that you added a condition or something. So this kind of thing, it's not something I mean, it's just yeah, I guess now I have the hang of it. So I know how to structure those. And yeah, I can make these reviews. Kate Mueller: [00:22:44] That's a really good point that I think there is a distinction between "I am describing what changed here in terms of the work that I did to fix this" versus "I am describing this for my end user so that they know what I fixed." Florian Lefebvre: [00:23:04] Yeah, exactly. Kate Mueller: [00:23:05] And it is a little bit of a mindset shift because you have to think less about the work that you did and think more about what do my end users care about here? And if you're not used to that shift, it can be really hard to write a good description of the thing. Florian Lefebvre: [00:23:22] Definitely. Kate Mueller: [00:23:22] And once you make the shift, you're like, okay, what do they actually need to know here? They need to know that this was broken and I fixed it, and now this is how it should behave. Or it used to behave this way and then it got broken and now it behaves the way it used to again, that was my fix. But it's a shift in emphasis: instead of looking inward at the thing you did, you're looking outward at what people need to know about the thing that you did. Florian Lefebvre: [00:23:47] And in a way, you have to do both. You have to do the public facing really what you fixed for the user, but you still need to say what you fixed internally in the PR description so that the reviewers like me know what's going on. Kate Mueller: [00:24:03] Yeah, that's a good point. I'd imagine that's a thing that a lot of folks early on struggle with is that idea of writing this for two audiences, one of them being the people reviewing this and one of them being the actual end-users who will benefit from the change. Florian Lefebvre: [00:24:19] Yeah. I mean, usually for new contributors when they write changesets, we do suggestions that basically rewrite the whole changeset. And usually the train set can be quite huge, like ten lines. And that can fit in one sentence. Kate Mueller: [00:24:39] Yeah. You actually did more work than you needed to do here. Let me show you how to do less work, which I'm sure does appeal to all of us who are a little bit inherently lazy. If there's a way we could do it in one sentence instead of ten, let's do it in one sentence. But there is an art to that also. And sometimes it takes a bit to learn that. I really love that so much of what it sounds like the PR review process is for you is a lot of cultivating those skills and talents so that the people submitting docs PRs learn, internalize some of those style choices or learn a little bit about, “Oh, well, with a changeset, here's what you want to do. It's not a massive thing.” And so there's this. Let me teach you about our styles. Let me teach you about the different types of documentation we have so that you can be more effective at doing that work moving forward. Florian Lefebvre: [00:25:32] Yeah, definitely. When we can, we try not to do the change ourselves, but we tell the contributor, look, this is how it should be and why. Or usually the suggestions are pretty transparent. But yeah, I think for the next contribution, usually it helps. Kate Mueller: [00:25:50] Yeah. And that's very true to the open source community in general, I think, that, like, let me teach you how to do this instead of just overwriting what you did to do it the “right” way. Florian Lefebvre: [00:26:03] Yeah. And to be fair, for some private projects, some clients, we also use some changesets and this kind of stuff. And I love that I can take this knowledge from open source and bring it to even private projects, because it also matters for private projects to have useful changesets, useful docs, these kinds of things. I'm like, okay, I'm going to do this this way because of the way we do it in Astro. And you can see in Astro Docs Docs why we do it this way. And it's really, yeah, it's healthy actually, I think. Kate Mueller: [00:26:38] Yeah, I think it helps you model good behavior for those private projects, right? Like, hey, we do it this way at Astro Docs Docs. (I love that it's Astro Docs Docs, also.) We do it this way for these reasons. And here are the benefits of doing that. Let me show you what that looks like here. And you can maybe help model some good documentation behavior for those private projects, which is great. I mean, as far as I'm concerned, better documentation makes the world a better place regardless of where it's happening and who's doing it. So. Florian Lefebvre: [00:27:09] Yeah, definitely. Kate Mueller: [00:27:11] So that's helping to make the world a better place, which we all need more of in this day and age. I also have a question, not necessarily about Astro Docs, Florian. So you're officially obviously doing some documentation here, and it's the first time you've done official documentation. But have you done documentation for yourself over time? Especially since so much of your learning in this space has been self-directed, right? You watched YouTube videos, you played around with stuff, whatever. It wasn't a formal university program, etc. Did you create little cheat sheets for yourself about how to do stuff so that you wouldn't forget like, “Oh, there's this weird trick here that if I do it this way, I'll remember it.” Because I know for me, that's how I got into documentation. It's that I have a terrible memory, but it was a little bit like, “Oh, I only use this thing like once every 2 or 3 months and every time I forget how to use it. So I'm going to give myself a little like five-step cheat sheet about how to use this thing.” Do you have anything like that where you created documentation just for yourself without thinking of it as like technical documentation? Florian Lefebvre: [00:28:24] No, I did not and I think it's pretty bad. It happens fairly regularly that I'm like, I knew I did this thing like a few months ago. Where the heck did that happen? And then I'm going on GitHub and searching on GitHub for this specific syntax or whatever. No. So yeah, actually, I think I should even just a Notion or something like that. Kate Mueller: [00:28:45] Something, just dump it in there. Florian Lefebvre: [00:28:47] Yeah, I have too much stuff just somewhere in my brain and at some point it just is deleted. Kate Mueller: [00:28:56] Yes. You can only hold so much in there. This is my problem also. So I think this is my little plea to you. You've now gotten into this habit of doing documentation for Astro Docs Docs. I think you should start doing some documentation for yourself so that you save yourself that, let me go dig through 8000 GitHub PRs or changes so I can find the one thing I need from six months ago that I only half remember where it was. Florian Lefebvre: [00:29:23] Yeah, definitely I should. Kate Mueller: [00:29:27] And you know, now that I'm nagging you about things you should do, this might be a good time for us to take a break before we go too far down that path. Kate Mueller: [00:29:34] This episode is sponsored by KnowledgeOwl, your team's next knowledge base solution. You don't have to be a technical wizard to use KnowledgeOwl. Our intuitive, robust features empower teammates of all feathers to spend more time on content and less time on administration. Learn more and sign up for a free 30-day trial at knowledgeowl.com. Kate Mueller: [00:29:57] And we are back. So Florian, I'd really love to hear a little bit more about the docs lead side of all of this, because a lot of what we're talking about here is people contributing PRs to Astro Docs Docs and what that process looks like. And I have to imagine that there's a lot happening behind the scenes from your docs lead to make a lot of that happen. So maybe to start with, how much of a role does, Sarah is her name, right? How much of a role does Sarah play when you're working on documentation for, let's say like the Fonts API, for example, because that sounds like it was a big, huge new feature in essence. Where does she come into that process? What does she do? Florian Lefebvre: [00:30:43] Yeah. So that's a very good example, kind of an extreme example in some way because it's really a big feature. So yeah, it touched many areas. For such a feature, first of all, that also touches the code side, but there are stages. We have RFCs. They are stage one, stage two, stage three. And stage three is the implementation phase. Still, this is still on the code part, right. And so I'm going to make an API, design it, and then there will be some back and forth between me, other co-maintainers, including coders and people on the docs side, who are going to tell me, “Oh, this API is pretty bad for X or Y reasons.” So to be relevant to what you are asking at this stage, the docs people are really important because from purely a user point of view, maybe the API is bad. I have been doing this API for three months. I know exactly how it works, how to use it, but I'm the only one using it. Yeah, it's not intuitive, maybe. Kate Mueller: [00:31:46] So you get a slightly outside perspective. Somebody who hasn't been eating, sleeping, breathing the thing who gets to be a little bit like your first user who's like this, this part doesn't make sense to me at all. Florian Lefebvre: [00:31:58] And I think that could be true for someone who doesn't do docs, right? But I think and especially Sarah, like she comes with the point of view…I mean, she has the beginner point of view in mind. So when she reads the API, she's like, “This is really obscure” or, this kind of thing really, I think it is pretty useful. So that's even before writing docs or maybe that is discovered in the process of writing docs, like when I'm writing docs, then we figure out that maybe the API isn't quite right just yet. So that's like the early stages where she would just help me. Kate Mueller: [00:32:38] And she's providing feedback on the feature a bit at that point, right? She's coming at it with that beginner mindset and just saying, “Hey, these are the bits that feel awkward or, or maybe just a little confusing.” So nothing to do with docs at that point, just thinking about the feature itself. Florian Lefebvre: [00:32:57] Yeah, exactly. But then so for such a big feature like Fonts, the first step in terms of docs is writing one big page for the feature because it's first released as experimental. So to keep things simple, we just put everything in a document and we try to have this document just as good as the rest of the docs. Being experimental is not an excuse to have crappy docs, basically. Kate Mueller: [00:33:25] Oh my god. I might pull that as the quote: “Being experimental is not an excuse for crappy docs.” Yes 100% Florian Lefebvre: [00:33:30] And also, to be fair on this topic, this is actually like a hidden advantage, which is if you have amazing docs while it's in experimental, then stabilizing it, it's just not a lot of work. You split the thing, split the document, put it in the right place, and you're basically good to go. So no, seriously, this is like a big advantage. But yeah, even at this stage of the experimental docs, usually the way this goes is I write something like that I think is right. And then Sarah goes in and says, “Okay, I wouldn't structure it this way.” Not looking at the details because to take an example, the API, I'm just grabbing the example there. It touches several parts of docs. For example, there is kind of a guide to how to use the feature quickly. For example, there were several font providers, so we have to document in detail every font provider and their options. And then we have a whole configuration reference for how to use fonts in the Astro config. And then there is also a reference for how to build a font provider. [00:34:44] There is a lot of stuff and it's useful to structure it well, very, quite early because it's easier for users. And it's also easier for us because from what I just said, like all these sections, that makes it very easy to then split into stable docs at some point. So yeah, that's the first stage. And then when we come to stabilizing, again, I knew some parts were pretty obvious on where to put them and some were not. So I was like, “Hey, Sarah, I'm thinking to put this in this location in docs or maybe I don't know, what do you recommend we should do?”. And from there, we split things up, and then we also have to clean things up because there are some mentions of experimental or we have to make it stable already. There is still quite a lot of work between going from experimental to stable, even if the experimental docs are very good, but it's still way less work. Kate Mueller: [00:35:46] I like that you start with a single page for the experimental feature, even though I'm sure that that ends up being, in some cases a fairly long page, but that it gives you that, “Let me think about the pieces of this, the guide versus the reference sections”, right? So you're still thinking about those different types of content that will eventually probably become separate pages, but you're not having to think about the architecture of all those separate pages yet. You're just thinking about the stuff that goes into each of those sections. And then it's not until you get to the stabilized feature docs that you're actually splitting those out and putting them in other places in the docs. Florian Lefebvre: [00:36:31] Yes, exactly. And also, it's great because we can write it in Markdown/MDX because at some point, like a few years ago, it used to be inside JS docs only. So inside, because some of the docs are right is written sorry in the docs repo as Markdown, and some of it is pulled from the actual source code because we pass JS docs and whatnot. And so yeah, it was an absolute nightmare to write a full experimental page in JS docs. It was terrible. Kate Mueller: [00:37:04] Yes, Markdown would be a lot easier to work on in that context. I mean, generally Markdown is a lot easier to work in. Florian Lefebvre: [00:37:12] But yeah, something I didn't say just now is like, so we are in terms of docs, there are changesets. They are actual docs, but there are also JS docs. So for things that really stay in the editor for the user, when they code. But some of these JS docs are pulled into the docs repo to autogenerate some pages. So that's that. And we have a whole file for error messages because we want the best error messages so that people don't struggle. And so this is also a thing on its own, writing useful error messages. Just a little aside. Kate Mueller: [00:37:54] Yeah. That's great. Honestly, error messages for me are one of those places that I think people don't spend enough time thinking about the wording that they're using. So I love that you mentioned it at all because if you can be clear about what the error is, it just makes it a useful error. Whereas if it's vague, people are like, “Well, something's wrong. I don't know what it is, but” or “based on the wording, it could be one of five things I think? Maybe not.” But I do really love that workflow that she's, in essence, made the choice to say, we'll do a single page for this nicely structured into those different components, but a single page for this so that it's easy to put all of it in one place, especially since I'm assuming experimental stuff evolves. So if you spent a ton of time on those details and then you rewrite half the feature before you/as you stabilize it, you're having to redo a lot of those really detailed sections. I also really love that it removes the pressure of content organization quite a bit. So instead of being like, “Oh, let me think about where this guide should live and this set of reference material should,” you don't have to think about any of that in the beginning. You can just think about getting the content built out on that single page and then as the feature matures and the docs mature, then you can start thinking about, okay, where should this guide actually live in relation to other guides? How do they connect to other things? I'm assuming that that’s a place that Sarah adds a lot of assistance as well, is that like, oh, this would tie, we should add references to this in these places because the features feel related. Florian Lefebvre: [00:39:40] Yes, exactly. She has the bigger picture in mind. And so yeah, that definitely helps to link things where they should be linked. And also, just a note, this is kind of extreme in a way, as I said, because it's a big feature, it's really huge. But for most experimental features, it's most maybe not most, but some. It's like literally a flag. So it's way simpler. It's still its own Markdown file, but it's yeah, it's like three sections and we are done. So yeah, it can really vary depending on the feature. Kate Mueller: [00:40:20] Now does Sara give you templates for any of these things? Or do you have examples of pages that you refer back to that you're like, “Oh, this is a great example of what a, whatever looks like a guide versus a reference versus a something.” What kind of process does she have there to help you stand up those new docs? Florian Lefebvre: [00:40:44] Yeah. I don't think we have templates per se. But yeah, usually there is always a precedent basically at this stage, which is great. So yeah, basically we go to another page, which is very similar in terms of structure or purpose. And that's what I did at least. And then yeah, just repurpose it for the thing I have to do. So it's pretty, it's pretty easy because there are plenty of examples already. Kate Mueller: [00:41:12] Which is in essence what a template is. It's just like, here's an example of how you should structure the thing. So you can also just pull an example. I mean, this is one of the things I tell folks when they first start talking about using templates. I'm like, well, first off, just find a good example of that that you already have. And then if you want to make a template, you just make that genericized, that example, and there's your template, or you can just tell people to use the example and swap the stuff out. It doesn't have to be fancy, but I think having those good examples really helps. It helps you understand what that content should look like without having to explain a lot of it to you because you can see it, right? That sounds really helpful. And is there anything else in that process that Sarah does along the way? Like I'm assuming for stable features maybe at that point she's getting into the details of the actual individual sentences maybe or something like that? Florian Lefebvre: [00:42:16] So for this feature in particular, and even in general, if something is added to docs, then it is reviewed extensively. Even as experimental, we took the time to go through sentences to make sure it's as clear as possible. Yeah. So as soon as it's added, it must be clear and good. So the fact that it was stabilized didn't change much in terms of sentences themselves, like make sure they were great before. Kate Mueller: [00:42:45] Oh that's good, that's good. And how has that been for you, Florian, as a French speaker first and an English speaker second? So I'm assuming also writing that there might be a little bit of like, “Am I doing this right? Is this actually how this sentence should sound?” Is that a thing that Sarah also helps with just the like, “Yes, that's perfectly valid English” or “No, we're going to make this small tweak so that it is perfectly valid English.” Florian Lefebvre: [00:43:14] Yeah, definitely. It's amazing to have someone who can tell you that what you just wrote isn't really English sounding. So yeah, no, honestly, it's great. I mean, most of the time it's fine. Usually it's like swapping the order of the sentence or you have little Frenchism. I don't know how to say it, but you get the idea. Kate Mueller: [00:43:35] And those like little, sometimes it's idioms, sometimes it's different languages order certain types of adjectives differently. French and English have very different ideas about this. Florian Lefebvre [00:4349:] Oh, yeah. Kate Mueller [00:43:50] So I say this as somebody who's been trying to learn French. And sometimes I'm like, I don't understand why that order is that way. And it is so helpful to have somebody who actually does understand be like, “No, you want this one first, not that one.” Florian Lefebvre: [00:44:03] So yeah, exactly. This is really like, it removes a pressure for me to know that in the end it will be good English, even if I had the ideas right and the writing mostly right, but not quite there. And it's also a bit funny because obviously for docs, there is not only Sarah, there are other people. And there is another co-maintainer, Armande, who is also French and who has been doing a lot of docs work recently. And basically like the joke is, you know, if Sarah, I mean, we are, we'll end up writing some French sounding docs because we are too many French people writing. Kate Mueller: [00:44:39] So many French people working together and you're correcting each other's stuff. Yeah. Florian Lefebvre: [00:44:44] So I think it's pretty fun. Kate Mueller: [00:44:46] Yeah, that is fun. And there's a thing you just said that I want to pick up on, which is that idea that it's that part of what her role is doing is removing stress there, like stress about how the English sounds or stress about like, where do I put this? How do I make sure that it's linked to all the right places? I think this is something that technical writers often forget, that a big part of what we do is that just by being present and doing the work that we do, we can remove stress for other people and just be like, actually, that's not a thing you have to worry about. Do not worry about whether that's flawless English. Just worry about whether you've actually described the thing accurately. And then I can tidy up anything that might not be flawless English. And let's be real, even as a native speaker, I don't always write flawless English. But I think there's a huge value to that role to just be like, “Hey, don't worry about creating all these separate pages for an experimental feature. Let's just do it in one page and then we can worry about how to split it out later.” Kate Mueller: [00:45:52] And that gives time to think about information architecture and all those other things without dropping that stress early on when it's still experimental, just like, reviewing the actual content means that you can tidy up the English a bit, but it's much easier to tidy up the English when the content itself is good. When you've got somebody who actually understands the feature writing about it and explaining it and that's much easier to me. That's way easier. Some of my developers, I'm like, give me a bullet point list of how the feature works and I can turn it into paragraphs. If it's that stressful to you, don't worry about writing pretty sentences. That's my job. But I need you to explain how the thing works. Because if I just go based on what I think it does as a first user testing it, I'm going to miss important details. I'm going to miss good nuance. I'm going to miss some of the stuff that actually makes the feature great. And you, as the person who built the feature, you know what's in there. You built it. So tell me what that is. Florian Lefebvre: [00:46:55] Yeah, exactly. Like I think it's super relevant to something else as well, which is as an open source project, it's all remote, which is great. I mean, I love working from home, right? But it has some challenges, like trying to convey what you, what the feature is actually supposed to do. So the fact that we have this talking and doc-ing calls is amazing because usually I would make a draft PR with what I think is right. And then on these calls, we would discuss maybe for 15 minutes, maybe for an hour or two hours. It doesn't matter the time it takes when going through the stuff I wrote and Sarah really trying to understand to make me say, what is the feature technically doing? It doesn't have to be friendly in the way of friendly to read, right? But you just have to be technically correct. Kate Mueller: [00:47:51] I was imagining her just like yelling at you at this call when you said that. I was like, I don't think that's what he meant. Florian Lefebvre: [00:47:58] I promise these calls are very calm and great. But yeah, basically, like it's really useful to have this process of she asked me, “Okay, you wrote this. This is the way I understand it. Did I understand it correctly?” And I'm like, “No, it's absolutely not this,” or “Yes, it's this and then this.” There is this whole process of, yeah, I think Sarah, to understand the feature. So then she can write or rewrite some of the stuff I meant. And it's just, yeah, it helps a lot. Kate Mueller: [00:48:29] I love that you do these as calls. I also love that you call them talking and doc-ing. That's fantastic. I might steal that. Florian Lefebvre: [00:48:36] It's awesome. I love it. Kate Mueller: [00:48:38] That's so good. That's so good. But I think that's a really important point that like, okay, let me go through this here as a reader is what I took away from this. Is that actually the way it works? And it sounds like there are definitely cases where you're like, no, that's not what I meant at all. Florian Lefebvre: [00:48:56] Yeah. Kate Mueller: [00:48:59] And that I think is so key when you're having people write documentation who aren't writers is to be like, “Okay, thank you for this. Here's a summary of what I understood from that. Is that right?” That is so important because otherwise she would be making edits based on her understanding, which might be completely not what you meant, and isn't how the feature works. And you really need that intermediary step of someone saying, okay, here is based on what I just read, what I think is happening. And that sort of confidence check to say, is this right or is it not right? Is it like 70% right, 50% right? Let's figure out what's not right about it, because that totally changes how she would approach editing that page. And I think far too often, especially in remote environments, people just take that at face value and they're like, well, clearly they meant this because that's what I took away from it. And then they make this big series of edits, and suddenly the feature is being described in a way that doesn't remotely describe what it's doing. It's a very awkward game of telephone. And I really love that that's a big piece of the process. So you said those calls could be 45 minutes, two hours. Tell me a little bit about them. Florian Lefebvre: [00:50:18] Yeah. I mean, I'm not necessary to all of them, but I mean, usually the call can be. Yeah, it really depends. But yeah, most of the time it can last 2 or 3 hours. And within this time there are several topics. For example, you are going through PRs or, yes, for example, I could say before the call, “Okay, I would like to discuss this draft PR I just made, and I'm sure it's going to take a big slot, for example.” So yeah, it's pretty informal in a way. It's just like, okay, we want to discuss these topics and if we don't have to, if we don't have time for this topic, well, it will be next week. Kate Mueller: [00:50:55] Is that like a group call? Is it a one on one? How does it work? Florian Lefebvre: [00:51:00] Yeah, it's a Discord call. So it's public usually it's what, ten, 15, ten people. It's not a huge thing. It's mostly for maintainers or people that are quite active. Kate Mueller: [00:51:12] Florian. This has been just an absolutely delightful conversation. Also, Sarah is the reason you applied to come on the show, right? So can we also just give Sarah a little shout out? Thank you for encouraging this lovely fellow to come on the podcast, because it has been delightful. And as a reminder to everyone this year, we are very much trying to get people in who aren't official tech writers. So if you are a developer who is writing docs or a marketing person or a support person writing help center docs, please go on thenotboringtechwriter.com, hit suggest a guest, send us your info or your coworkers info. Maybe we'll have them on the show because that is how we got on and he's amazing. So there must be more of you out there. And Sarah, thank you for strong arming him to get him to come on here because it's been great. So we've talked about a whole lot of stuff. Are there any resources that you would like to share? I will definitely share the Astro Docs Docs site because I think it's delightful. Sarah's put together some lovely guides on there to try to get people to contribute. We will also share the official Astro Docs site so y'all can go check out their docs. I know we've got some folks who are looking for projects to contribute to at this point, so I'm hoping by sharing some of this, you might get some folks who might contribute some docs PRs, maybe, or might contribute on the dev side, who knows? But are there any other resources out there? They don't have to have anything to do with writing. They could be resources you just love as a developer that you would like to share. Florian Lefebvre: [00:52:51] Yeah. To be fair, I prepared some docs related resources and it's not necessarily things I use. I use it a lot, but I know that are useful, for example. So yeah, obviously the Astro Docs Docs like pure gold. Kate Mueller: [00:53:05] I loved it. I actually went and checked it out a bit before we met. There's some great stuff in there, so we'll definitely share that one. Florian Lefebvre: [00:53:12] Another thing is I know Sarah has structured Astro Docs, at least to some extent based on the Diátaxis framework. So which as far as I know, is like allowing to structure docs based on different goals. So you have references, tutorials, this kind of stuff. So I think that's pretty useful. Kate Mueller: [00:53:28] That framework has come up several times on the podcast. I think it's a useful framework for people to think about how they are structuring documentation, whether that's individual pages or individual sections of pages, or a bit about how you organize your site overall. Yeah, we'll definitely throw in another link to Diátaxis because people love it. Florian Lefebvre: [00:53:50] And yeah, I guess last resource is on Sarah's blog, which is rainsberger.ca. She has 50 docs tips in 50 days thing. Kate Mueller: [00:53:59] Oh wow. Florian Lefebvre: [00:54:00] Yeah, there are a lot of tips and honestly, it's great. It's not like. It's short things, but it's great. So have a look. It's great. Kate Mueller: [00:54:08] Ooh, yes. We'll definitely have to link to that. Maybe moving out of writing stuff specifically in any way, what is a great piece of advice you've been given? Doesn't have to have anything to do with writing. Could just be life advice. Florian Lefebvre: [00:54:21] To be fair, I kind of struggle to find something. I was like, I'm not remembering anything special. Will be very related to Astro Docs again, which is like we have this little sentence that is much more than what we had before. Yeah. Basically, you know, it can be a little improvement. It doesn't look like it's a lot. Maybe like from a new contributor perspective, but these little improvements just add up and it's great. And especially in open source projects like you are fixing a typo, you don't think it's much, but you are improving the thing, you are getting familiar with the project. Maybe you can contribute some more stuff later on. So yeah, not worse than what we had before. We even have a custom emoji on the Discord for this. Kate Mueller: [00:55:07] I love that. But it's true. I think sometimes people put a lot of pressure on themselves to feel like I have to do something big and important. And the fact is that a lot of large projects get moved forward by these tiny incremental changes, right? Rome wasn't built in a day. Rome wasn't fixed in a day. Your product is not going to be fixed in a day. The thing you're working on will never be complete, but doing those small changes that continue to just slightly improve. If you look back at a year of small changes, look at the significant amount of improvement you've had. There's your big project, right? But you got there in a much more sustainable bit by bit way. So I love that. And lastly, Florian, if anybody listened to this episode and was like, oh my God, I love this guy. I'd love to see more of what he does. Or I'd love to pick his brain about X or I really want to get more involved in the Astro community, and here's a person I could actually ask about that. What would be the ways that you would want them to get in touch with you? Florian Lefebvre: [00:56:15] Yeah, sure. So you can reach me on my website, florian-lefebvre.dev. Not the easiest URL for non-French speaking people, but anyways. Kate Mueller: [00:56:25] We will link to it in the show notes. So do not feel like you have to try to guess at how to spell that last name. Florian Lefebvre: [00:56:33] Yeah, yeah, it's not the easiest one. But yeah, I mean, a bunch of social links linked there. My emails are open. So yeah, feel free to drop me an email and I'll answer. Kate Mueller: [00:56:43] Beautiful. Well, thank you so much. Thank you for your time. And thank you for the work you're doing on Astro, both on the framework itself and on the docs, because it's a delightful framework to use. Florian Lefebvre: [00:56:56] Yeah, you're welcome. It's also delightful to make. So it's great. And yeah, thanks for having me. It was a very, very interesting experience because yeah, this is my first time on a podcast. Kate Mueller: [00:57:07] See? You're writing technical documentation, you're coming on podcasts. Who knows what's happening next? I don't know, something amazing. I can just tell. Florian Lefebvre: [00:57:19] I hope. Kate Mueller: [00:57:19] Thank you. Florian Lefebvre: [00:57:20] Thank you. Kate Mueller: [00:57:28] The Not-Boring Tech Writer is co-produced by our podcast Head of Operations, Chad Timblin, and me. Post-production is handled by the lovely humans at Astronomic Audio, with editing by Dillon, transcription by Madi, and general post-production support by Been and Alex. Our theme song is by Brightside Studio. Our artwork is by Bill Netherlands. You can order The Not-Boring Tech Writer t-shirts, stickers, mugs, and other merch from the “Merch” tab on thenotboringtechwriter.com. You can check out KnowledgeOwl's products at knowledgeowl.com. And if you want to work with me on docs, knowledge management, coaching, or revamping an existing knowledge base, go to knowledgewithsass.com. Until next time, I'm Kate Mueller and you are The Not-Boring Tech Writer.