Claire Waters 0:19 Hey, everybody, Thanks, Brian. It’s always funny to hear somebody else, like read your bio out, and I think it’s like a little unsettling, especially as a tech writer, when we’re the people behind the scenes doing all this stuff. But like Brian mentioned, I am here from Cloudflare. We’re super excited to be sponsoring the event today. If you’ve heard about CloudFlare, you might know that we do CDN products. What you might not know is that we also have a whole suite of tools and applications for developers. So we have a whole developer platform that enables you to build and deploy on Cloudflare. We have compute functionality, we have database and storage products, we have media solutions, we have aI products. So we have a whole bunch of different things that help enable you to deploy and develop code faster and more efficiently, it’s also Cloudflare birthday week, where every year during the week where we were founded, we announced a whole bunch of different things and initiatives to help kind of give back to the internet. So rather than, like giving getting presents, it’s cloud for his way of giving back. So if you’re interested in any of the announcements, definitely check out the Cloudflare blog this week. A lot of exciting stuff happening, especially around like the open source space soon, but you do not want to hear all about Cloudflare. You want to hear a bit about Cloudflare and Docs. So with that, we’ll kind of dive into the presentation. Admittedly, I was not supposed to give this. So my coworker, Kody Jackson, had him and his wife had their first baby last Friday, and he was supposed to be doing this. I am pinch hitting for him. I know all this stuff. Kody and I are two halves of a whole, so all this is familiar, but if there’s anything in the presentation that you don’t like or don’t agree with, just assume that it’s Kody’s slides. So today, we’re gonna go ahead and dive in. I know that a lot of you are code you know are either developers or technical writers yourself, so some of this is just info sharing about how we manage our docs at Cloudflare. I always find it really interesting to learn how other people in industry are doing this, whether you’re a small startup or with your supporting enterprise customers, or an enterprise company yourself. We’re going to talk a bit about kind of CloudFlare, our tech stack, the things that we do, how we support our docs, how we manage ourselves as an open source docs product. We’ll dive a little bit into analytics and share some practical advice about just running docs teams and supporting the tech that runs documentation sites, and we’ll do questions. So with that, Cloudflare docs has a lot of content, so we have over 4000 pages, and we’re still growing. Everything that we do is on developers.cloudflare.com, so essentially, everything on our site is is documentation that isn’t focused just a developer docs, but it’s all within that domain. So we do have the developer docs. So application API, reference, code examples, tutorials, etc, the how tos of how to actually do something in our UI or our CLI. A couple years ago, we actually took over all of the knowledge based content that lived differently in our support portal for a while, and we brought it all together because we were realizing that people didn’t want to have to switch between a KB and a Doc site to figure out what to do to solve their problems. We also have reference architectures in our site, which is a little different. Oftentimes you’ll see those in like marketing sites, but we found that customers were coming in trying to figure out what Cloudflare was doing, and then wanted to quickly move on to well, how do I actually do it? Now we also have our API documentation for our REST API schemas, technically that lives as part of our domain, but it’s essentially a separate microsite that’s managed by a different team that we support, like the content reviews of it. So in addition to having a lot of content, we get a lot of traffic for a website in general, let alone for a documentation site. So we’re going to talk a bit about like, what the implications of this are for the rdocs team, but part of it is that we just offer a lot of services. Cloudflare offers every almost everything that the hyperscalers do, but, you know, in a slightly different footprint. So we just have a lot of things. We have a lot of free users, and offer a lot of our products for free, which we’ll talk about in a second. And so with that, people are going to first default to the documentation to solve their problems, and, you know, implement what they’re trying to do with Cloudflare. So docs end up having a lot of impact. There are also just a ton of things that we can do with analytics, because we get so much traffic at such a high volume, that really makes it easier for us to make decisions about like where to invest in our content priorities and how to how to solve certain problems. So our tech stack looks a bit like this. We host our site on Cloudflare pages, which is a Cloudflare product. We have a generous free tier. And you know, our product can help and help deploy our applications quickly. We use Starlight by Astro for our framework. We. Actually made that transition in August of this year, and it’s been really successful. We had kind of used a homegrown, piecemeal solution for our components prior to this, and moving to Starlight gives us the flexibility of a bunch of components in a much more sustainable way. So we’re not sort of hacking together what we want the site to look like. We can use some of the standard components from the start. We use doc search by Algolia for our search. They also offer a really good free tier. We host all of our content on GitHub, again, free tier of products. If that’s something you’re interested in using, we use zaraz, which is one of our Cloudflare products, for sending tracking data to Google Analytics and amplitude, and then we manage we use a subdomain setup to manage our site, that is an enterprise thing, but there’s a lot of different cloud for products you can use to help manage your your docs, your your site hosting. Okay, so you heard me mention a few different open source projects in our tech stack. We also use our actually here I’m gonna go back before the SpongeBob reference. We have our docs open source, and there are some interesting problems that come with that. So let’s like, kind of quickly do a scenario. So if you happen to stumble on some of these documents, you see that there’s a typo or a formatting error or a broken link or something, you’re like, Oh, that sucks. I can’t believe that got into production, that’s such a bummer. That’s so annoying. It’s breaking my workflow. It’s throwing me out of the task I was trying to do. And it hurts a little bit inside, especially as like a docs person, right? And then you wait, and you’re like, Okay, well, I’ll give them the benefit of doubt. People make mistakes, and then you go back six months later, and it’s still there. And just so frustrating to be like, how could somebody have not caught this little typo in these docs? So the goal of having open source Docs is that everybody contribute. So as one of our product managers said, their goal is to make docs everybody’s problem. So it’s that goal is to make the docs a little less eye bleedy, if you will, for everyone. So when there’s problems, it’s really easy to say, hey, you know what? That link is broken, or this is a this is a mistake, or this is referencing something incorrectly. Enable your users or your internal stakeholders to quickly file an issue, or PR suggest the change, have it reviewed and merged by tech writer and then addressed quickly, so it keeps things moving in the documentation space faster than just like relying on a tech writer to go back through and see that particular doc and catch that particular mistake, it also really makes it easier for us to listen to our community and what the things are noticing. So it just fosters this really collaborative environment that, like they see the Docs team in our GitHub repo, addressing changes, making improvements, creating new content. They know that we’re in there, we’re paying attention and we care. So they’re more prone to suggest changes, because they know that we’re going to be seeing it and actually contributing to it. It also makes it easier for like, working with internal stakeholders. We are a finite resource as a tech writing team. We can’t support everything. So in places where we’re not able to support a certain product, because maybe it just like, isn’t the priority. Isn’t the priority, or we have other things, you know, superseding it. At that point in time, we are able to, like, say, hey, you know, if you propose the changes, we’ll take a look at it, and you can push them live to the site. The goal is not to take advantage of any of the free work or goodwill, though, at the end of the day, we are a Docs team. We have a docs engineer. We are a for profit company. We don’t want to take advantage of any of the work that the great work that the community is doing. It’s incredible to see that people are really invested in helping keep this fresh and relevant and up to date. But we also don’t want to abuse that at all by any means. So it’s kind of a balance of helping people feel unable to contribute, while also acknowledging that, like we have people to handle these things, and so it’s a kind of a conversation in a lot of the issues in PRs and spaces that we have. So when you’re a tech writer, doing the tech writing, is really easy to kind of conceptualize the value that you have over the thing that you’re doing. So you say, This is my space, this is my precious environment that I’m owning and nobody else can like touch. And I own the source code for this, and I own the improvements, and I’m the one, you know, taking all of the feedback and making sure things are happening, it kind of becomes an inherent part of your value as a tech writer, like this is my space in my lane, and I’m going to do all the things for this, because it’s mine. But the cool thing about having things open source is that it’s not just you, it’s the whole team. And like I was saying a minute ago about us not being able to support everything, this allows us to lean into the other groups that might have more experience with that particular thing. So maybe it’s the product manager who’s understanding how customers are interacting with a particular product, or support who’s seeing issues with the product and noticing that we need to kind of explain it in a different way than we did when we did the initial product docs. It just makes it this really nice collaborative environment. And so rather than feeling like you just own the one piece and. Everybody kind of feels shared responsibility. So it elevates the quality of what we’re dealing with,

uh, Kody’s analogy. So referencing back again, some of the stuff is Kody’s is that it’s like managing a gym after New Year’s. So everybody’s really excited. They want to get in, they want to try things out, they want to test out the equipment. They there’s a bunch of enthusiasm. You’re like, yes, jazz to get in and try things, but as the Docs team, you’re trying to make sure that people are using the gym in a way that’s safe and functions correctly and doing exactly what you’re supposed to, so that nobody accidentally hurts themselves. Thankfully, usually the ramifications of making an error in the docs are less than like dropping a weight on your foot. But you know, it could always, could always happen. You might accidentally hit a laptop. So you might wonder, though, when you’re in an environment like this, why bother having technical writers? You just told me, Claire, that, like anybody, contribute and keep the dogs fresh. It’s just, why? What’s the value of a tech writer in this environment? Then there’s a couple really key places, I think, definitely in new feature development. So because technical writers are part of the internal team, they’re able to join the product manager, the engineering team, the design team, earlier in the process, to go in, learn how the product and prepare for its initial launch. So that way, when you actually are publishing your feature and announcing your new thing, you have somebody considering the content experience alongside that from the beginning. Oftentimes you also have technical writers providing that first usage feedback, right? So to document the product, we often have to go in and test it, which means that usually the tech writer is almost the first person in there looking at what the product experience that was. Experience that was developed is, so they can go in and really validate like, what what was built, and whether anything needs to change. Another really important part and role that tech writers can play is in defining what like the user journey through the product is, and how that maps through the content journey that supports it. That’s the slight. If you ever heard of like journey mapping. The slight difference between the way that I feel a technical writer should do it versus like a design team, is that design experience is trying to get to the ideal right. You’re trying to map out what that ideal user experience should be. Technical writers have to capture and document the world as it is today. It can’t be some ideal state that you’re working towards over, you know, 369, 1218, 24, months. It has to be what they’re dealing with in this moment today. And when things change, you can go and adapt that later. The types of content that this ends up identifying is creating comparison. Guys like how to choose between the different storage products that we have a workflow for how to go through a particular product, identifying gaps. So when you start having releasing a product and having it out in the world, people are going to use it in ways you didn’t expect, or people are going to use the product and realize it’s not doing exactly what they thought. And you have to document that. You can’t just say, okay, sorry. It’s not going to be a thing. You need to say, Hey, this is not working right now. This is your this is how you work around it and give people a path through that problem, and they’re supported in that through through content. Technical writers also help maintain so in talking about the that people file issues and PRs, those are on particular areas of the content. There are technical writers that own that content, and they can respond to those external and internal issues. The technical writer still oversees a particular set of content because, you know, it’s that sense of ownership, but also shared responsibility. We also help onboard new contributors. We help people get familiar with how to make pull requests, how to write things in Markdown, how to pull in images and design images, and then there’s just like the general maintenance that technical orders still perform, that you can’t totally automate, though. We’ll talk in a second about how we do so we look through, you know, what things are inaccurate, what’s no longer true about the documentation we created. How do we keep those types of mistakes from happening in the future? The nice part is, though, because it is open source, there’s a lot of stuff that we’re able to automate and experiment with, putting into different different tools. So as we’ve had more people contribute, external contributors to our PCX team. People are interested in like, knowing how they’re supposed to write something. They want to know what format am I supposed to use, what words am I supposed to use? How do I refer to this product? How do I refer to this type of thing? How do I pull in a code block in this way? So people were coming to us asking for, well, what should I do? What standards should I align to? So we published our style guide. We it’s kind of segmented in a few different sections. We have grammar, which is like how to say something, formatting, which is how to display something, content types, which is the like content container or the content strategy, and then like the components you can use. So notes, tips, asides. Yeah, those are all the same thing, steps, code blocks, images, links, all that kind of thing. People want to do the right thing, so they wanted to align to our standards. They want to have content that’s useful and relevant. They were asking us this, and we realized that we were doing reviews for these things, and started thinking, Well, what if there’s a way to change that and automate a little more how we’re doing those checks? So when we were considering different solutions to automate this, you know, you’ll hear frequently about linters, but we started how to we had to ask ourselves, what is like a break the build type of thing, like, what kind of check do we need to have for something that would cause serious problems for the documentation as a product? What would we what should we block a pull request on those end up looking like, broken links, broken images, you know, for things that would end up for for all that kind of stuff. How do we streamline the reviewer experience so technical writers were frequently making, you know, comments about certain mistakes, and are those things that we could automate? And then we also had to ask the does it actually break the build? And then also, how can I, as a writer, know of what’s coming in, what I’m supposed to be looking at? So at first, we just had everything dumping into our GitHub repository in issues and PRs, and it was like this huge list with no organization that you know, does every writer have to address everything? Is there any way that we can better solution this? Also, I just like, flown my coffee everywhere. That’s what I get for talking with my hands. So a couple of the things that we added here, we added in some GitHub action labeling. So a couple of these automations we tried, we got for free, one, a couple we built. So in here you can see that there is a label that happens every single time that you open a PR. So for us, this looks like the product label. This looks like assigning to the person responsible for that area. And then this one that says extra small is like the general size of that ticket. So that’s based on, like, the complexity, how many different docs it touches, how long the documentation is, how much net new contents in there we have. We have our pages deploy on our repo, so anybody that’s part of our documentation contributors group can see has access to this, and then they get a preview link when they build. So we went from doing almost exclusively local building to test the content to people feeling more comfortable pushing their PRs up, getting the automated link that changes every time you push a commit. And then also we get four before and after links. So this middle link of the preview build is for, like, the whole site, the down, down here in the the before and after links. That’s like the specific page you did. So when you’re sending it to a reviewer, SME for for input, you can see what like, what specifically changed and compare. So the other thing is that we started experimenting with, like automated rules and through a linter, through Vail, we have actually implemented this twice. The first time that we tried implementing veil as our linter, it we tried doing so many things that it was just too much noise to be helpful and actionable, so we pulled it, and then we sort of rethought like, what do we actually need to do? And then thought through like, Okay, what things really matter to us? What things are automated checks that we should put in there, and how do we improve this? So, like, an example for Cloudflare style is that you have to calculate the internet. It’s just a thing, part of our respect towards the internet as a company, and so that’s something we are constantly having to catch. And so hyperlink, which is a tool that we use a third party AI tool that catches these, goes through when you when an external contributor files a PR, and then we’ll reference this issue. So rather than being kind of this, like it’s yelling at you and did not tell and just telling you what to fix, it also provides a little bit of context for how you can fix it. So the In summary, kind of automation we have is that every commit there’s a required set of checks. Does it build? Does it have infinite redirects? Are there broken links? The optional ones, which might hurt a little bit our tech writer hearts, is that the style guide checks are optional. Like, it’s not going to break the bill and so we can’t make it a blocking check. You don’t have to have the preview build or the before and after. That’s just a again. Like, it’s nice to see, but it’s not going to break submitting that PR, every pull request or issue gets that label, the owner and the product label, and then, as needed, we have some tools we run manually, but they’re still autumn. They’re still automated checks which have to, like, trigger them manually for broken links, broken API documentation, unused images to clear up space, External links that have changed, etc. So we do all of that regular. Literally, to help minimize the manual work that we have to do,

and back on that Building Community Through all of this, it’s been a really interesting way of getting people to feel that shared responsibility for the docs, while also, you know, knowing that we’re part of a team together, even though you’re an external person. So you can see all of these were submitted for like, Doc site, stuff from this user named Kean, and he got to be really helpful. And it was reaching out to us and kind of giving some perspective on how to manage our docs set up, and some things like what we could do for the linter and what we could improve. And then, you know, noticed that we had an open wreck, and was like, hey, you know, I think this role would probably be the person to help you out with this long term, rather than me as an third party person. But turns out, that’s the type of job that Kean was also interested in, and so through a hiring process, ended up joining us. Is now our new Docs engineer is helping us address all these problems that he was doing a contributor, but now as a full time employee. So it’s been just this really rewarding experience to see these people helping us out, feeling like they own part of the docs, feeling like they’re part of this team, and then kind of taking it with the next level of like, well, hey, I’m feeling like I’m part of this team. I see what it’s like to work with the Docs team. Maybe I should consider joining, and it worked out in our favor. So it’s been a pretty cool thing. So we also do a lot with analytics, and when you’re doing docs analytics, I think the default is page views, and we’ll talk a bit about kind of the building blocks that we see for this, but it’s sometimes hard to know what you should do to to measure that you’ve actually had an impact. So this is very much Kody’s story, but he was a PhD history student who wrote, like a almost 200 page thesis. I think that he says less than five, five or less people read maybe, which is just like a little soul crushing, right, as you spend all this time, right? This super lengthy thing, and then nobody reads it. So one of the really energizing things about technical writing and creating content that’s on the web is you’re able to see, are people finding this? Are they reading it? Is it helping them do what they came to do? So we think about analytics in sort of like a stacking a stack rank of things that are, you know, easy to get, but least actionable to most valuable, but kind of harder to access. So like I said a second ago, page views, kind of, that base level, are some pages more important than others. You can see views on one page versus the other. You can compare. You can see what things people are landing on. Kind of the next level of that is, it’s coming from search traffic, right? So that’s tied to the SEO what terms are people using to get to this page that helps identify different gaps, right? So are there non docs pages that people are going to first? Are they ending up somewhere we didn’t expect? Should those actually be part of our doc site? Should be adding some terminology or context to the page that we don’t have. How are our docs ranking compared to competitors that do this? Then we have metadata. So within the individual page are certain subfolders, which is how we group our products more important than others. Are some content types more valuable than others. Are we seeing more traffic to the tutorials versus the How To Guide? Should be investing more in there? Should we change how we’re prioritizing content based on what we’re observing in the traffic from the metadata labels we’ve added? We use a few different metadata types. They’re all listed there. Kind of the next level of that is what custom events are happening in our docs that can tell us more about how people are using them. So if we could see when using somebody was using something, is that helping us build more empathy with what they’re trying to accomplish for us in the docs that looks like a copy code. So we have a lot of code samples. Are people copying a particular code sample? Are they playing a video from within docs? Are they clicking out to one of our other Cloudflare domains? Are they clicking out to a different resource? Are they switching between the tabs to see how to do something in our UI versus the API? Are they scrolling down on a page? All those actions tell us that they’re engaging with that content at a slightly deeper level than just visiting the page. And then, kind of the most challenging, but one that’s able to kind of tell us the most impact is what’s that cross domain tracking? So in the context of the entire user journey, are they starting on the marketing site and then coming to us and then going to perform an action on the dashboard? Are they going to file support ticket after visiting a document? Are there things that we need to adjust in that content so that they’re more or less likely to go to a different space of Cloudflare and do something else. This is admittedly something that we’re still figuring out, but we’re starting to enable, you know, tracking in the right ways and the most GDPR compliant ways to to track that and kind of make some actionable inferences from the data we’re seeing. Yeah. Yeah, so it’s a lot. All of this is like, how we do it again. Just interesting to share. I think you know, when you’re in your lane, at a doc, at a team, it’s very easy to just sort of keep heads down and do the things that you’re comfortable and familiar with. So to kind of wrap it up with some some general practical advice, if you are a code person who’s starting to kind of try to figure out docs things. Remember that docs are for everyone. Documentation is both a product and something that supports other products. You have to treat it like a product owner. You have to make decisions for the experience of the documentation so that it can more effectively support the experience of the products writing is thinking when you’re having to write out the process doc of how to do the thing that you just built, or how to use the thing that you just built, you’re going to work through problems as you’re documenting it that you wouldn’t have otherwise, until you tried to explain to somebody else how to use it. Sometimes that also makes you realize that some of the choices you made during development might not have the right thing for your user, and that kind of sucks sometimes, because it means rework and having to go back through and change things, but it also means that your customers will be less likely to, like, hit that problem. Looping in writers, if you have them early, is really helpful. A lot of people will be like, Oh, we probably need some docs when it ships, but having a writer embedded earlier in the process, and even if it’s not early in the process, maybe during that QA or testing period, to say, Okay, let’s get somebody in here. Try to use this thing that’s not me as the person who developed this, and see if we can document it and explain how people are actually using it, and listen when your technical writer brings up feedback we’re not like while we may not be your ideal end user because we’re a technical writer, we probably are catching things about this product that your end user will end up catching also. Content is bigger than just documentation. Most of what I shared today was about decisions for our doc site. Content is UI copy. It’s the content design within your product. It’s error messages. If you have unclear or unactuable error messages, people aren’t going to solve their problems when they hit them. Documentation and content can write around a lot of stuff, but it can’t fix everything in the product. So really think about whether the thing you’re you’re getting feedback on, or that people are struggling with, whether it’s actually the docs or if it’s something in the product that needs to change. The docs can be more effective use cobbler. There’s my sponsor. Plug it in too. We have a lot of different tools that enable you to publish and deploy code globally to our network or global network very quickly. We use it. It’s been really effective for our static Doc site. We’ve seen some really cool implementations we started playing with for internal tooling for like, an automated AI that will review error messages or API descriptions for our stakeholder teams to help them kind of learn how to write better. And we’re using Cloudflare stack to do that.

If you’re a right, if you know a content person, and maybe you’re like, looking to get into tech, to technical writing is a great way to do that. I have two journalism degrees. I was always interested in science and tech and engineering, but ultimately chose to go with the thing I liked doing more, which was right. And this has been a really rewarding way to get into tech. And I’ve been here for over 10 years, and it’s just been really interesting to kind of constantly have to learn something new, always be willing to dive deeper into the tech, whether that’s through doc, site development analytics, trying out building code samples, any of that is just a really great opportunity to get more comfortable with all that technical capabilities that you have to know, because you’re eventually gonna have to, like, learn something technical, to document it anyway, use your products as much as you can. The best technical writers go in and try out their products independently to get things moving and to make sure that the product is working as expected. Analytics can change that conversation for you so they make or break the ability of you to tell the story of the impact that you have. So as early as you can lean into analytic tracking, to things that will move the needle, for things that your stakeholders or business leaders care about, don’t be afraid of AI. I think everybody as a technical writer has been asked, Well, what do you think about chatgpt and at the end of the day, AI tools need all the technical writing best practices to be true about content on the web. So good SEO, good metadata, good formatting, good structure, all that needs to be true about content that you’ve got. We’re using it for different things, using the tools from your internal tools, using like style guide checks to automated. The kind of repetitive pieces of our job is really it’s been handy in a lot of ways. So just kind of, don’t be afraid to try something out you don’t know until you start trying. And then also use Cloudflare. Look at that again. Most part of our tech stack are totally free. So if you’re interested in just like, what it could look like to quickly throw together. Or a static site that you want to try hosting and maybe try some integrations with Cloudflare has it also your content people, so you’re going to go look at our docs. Please feel free to leave us feedback. Let us know whether the content is helpful in getting you to do what you’re trying to do with us. And yeah, we’re always open to that feedback. Like I said, it’s open source. You can leave that that those comments for us, and so that is it from me. We’ve got our or you can go check out our docs and see whether I’m walking the walk as well as talking the talk. We have our Discord channel, if you do use any cloud products and are interested in chatting with other people that are using it, we have a really fun YouTube channel that’s gotten a lot more videos and attention lately, so some great people and personalities on that. And then if you’re interested in anything else or have questions, please feel free to reach out to me. And so with that, I think that’s everything.

Brian Rinaldi 30:54 I think it’s time for thanks. Claire, that that was, that was excellent. I love the I think it got to questions that, if anybody out there has dealt with Docs, like, we’re often having to deal with, like, oh, how do we set up the analytics? How do we determine, like, what kinds of automations to set up? And I know I’m dealing with those issues right now because we’re trying to, like, docs fall under Dev Rel right now at local stack. So like, I’m trying to figure out, like, how do we get our docs? You know, it’s one of those things developers love to complain about all the time. I always say, like, oh, you know, there’s a level of complaints about DOCSIS, like, acceptable, because developers just always like, yeah, now the docs are a problem, but, but, but I do know it’s something we have, we have to work on at our company, we, you know, we hear a lot about it’s hard to find things, and it’s that’s one of the hard things. Like, about when you have large stocks, like you do, like, how do we even find something and make it easy even then, you know, search sometimes, like, brings up 10 things. Like, how do we make sure that the most relevant things pop at the top anyway? Telling you all of my problems, this is going to become like a confessional here, but we’ll get to the questions first. First of all, one of the the audience asked if we can get a copy of the presentation. I don’t know if we, we haven’t actually set that up with you, but we will work with you afterwards to, like, hopefully, get a copy of the slides and we can share with everybody as well. We’ll kind of make sure to put it in a follow up email or something like that. And then actually, Sean got to a question that more or less I was going to ask myself, which is, he says, I love Starlight for simple doc sites, but I’m hesitant to use it on complex production sites. What do you like best about using Starlight at CloudFlare, and what are some of the obstacles you had to overcome to use

Claire Waters 32:49 Yeah, so I code heat Kody and our docs engineer Kia, were the ones that were most involved in doing the migration. I was kind of in the spot checking phase, but the things that I know that we’ve really liked, are the standard components. So before that, we were using Hugo, and we had built a lot of custom components to do things for us, to the point that it was getting pretty hairy to maintain every time somebody were going and making a change, and it was getting pretty brittle. So we something that’s great about Starlight is just has all those components. You know, by the start, from the beginning, we didn’t have to, like, rebuild any of those. We didn’t have to change anything we can just like, kind of use out of the box with some, like, minor tweaking for styling and things that we like. Some of the obstacles, I think our site is mostly static content. So Starlight handles it pretty well, because it’s not like applications, and not a whole lot less, if you’re interacting, like more you know deeply with your running running code on we are working through just some of like, the the restrictions that Starlight has. Like, for example, the top level nav item isn’t clickable or isn’t selectable without some customization. So, like that’s a change from the docs experience we had before. Honestly, the trickiest things have been just expectation changes from things that were true about our old site that are no longer choose starlight. So I don’t know that’s like anything specific that we’ve struggled with yet, but also, we’re six weeks into using it, so I’m sure I’ll have more input on that answer as we see more and more users engaging with the starlight site first?

Brian Rinaldi 34:24 Okay, yeah, that’s, you know, we use, I’ve used Hugo for a lot of projects, and we were using Hugo for for our docs and stuff as well. So I am aware of, like, the, you know, when you Hugo is great for build time, but, like, some of those, adding those components ends up being kind of a pain. So I’m curious though, whether you’re seeing like, is it significantly more build time with Astro given the size of your site? I mean, you’re talking 4000 pages versus no,

Claire Waters 34:57 no, we haven’t. I don’t have the nine. Members, but we haven’t noticed anything. So that’s like to I know we’re our our users and our internal speakers are people who would be like saying, Hey, this is unacceptable. It’s added so much time. Wow, yeah. So I can’t say that. I actually have. I can follow up with that, though, because I think I’d be, I’m interested in that question now too, about whether it’s impacted it too much for us. We I will say the starlight team has been fantastic. So because they’re also like, open source, they’ve been just super responsive to helping us work through things and letting us know timeline of like, what’s coming when and when we can expect different changes and improvements. So that’s also been a big plus for us, in that they’re, you know, caring deeply about their docs. But yeah, now, now I’m curious about the build time. I actually don’t have the answer to that. Okay, it’s not bad. I’ve been noticed. So that seems like a good sign. Exactly.

Brian Rinaldi 35:50 I would say, if you haven’t noticed it, because that’s always my worry when you’re getting into something that’s like a significant number of pages. Hugo can be like, blazing fast, but Astro and so far in my experience has been pretty quick, but i Anyway, be curious to know. All right, so we have another question from ember. Do you ever have concerns with customers seeing your open PRs in the public repo too early for new features coming out? Or do you have a method for holding back info you aren’t ready for customers to see it

Claire Waters 36:21 is somebody like, looking at my calendar and my chat history from this week, because this is, like, what we’re dealing with. So this is birthday week. We’re announcing a lot of cool stuff and releases, uh, lots of product announcements, lots of product changes and enhancements. People pay so much attention to our repo. Also, like, we put up a PR to add a new version AI site and had like 20 reactions in like five minutes, you know, just some something stupid that people are really in there. The way that we usually handle this is have the writers collaborate with the product team that’s developing that new feature in, like a Google doc beforehand, because it’s just the easiest thing to do. We do allow people to, like, you know, create private forks and do like, collaborate through that way, and then just merge it in when they’re ready. We found that ends up just being more effort than it’s worth. So usually we’ll like, collaborate on on a doc together and then just publish the PR as close to the time of the announcement as possible.

Brian Rinaldi 37:21 Yeah, that is a hard thing, right? Like, especially if you’re trying to keep something secret, yeah,

Claire Waters 37:27 we have. We’ve had a couple times where we’ve published something that they were like, not yet, please, and we’ve had to pull down. But that’s the nice part about the docs, is it’s easy to revert. So, yeah, yeah, definitely a problem.

Brian Rinaldi 37:40 Yeah, okay, that’s, that’s really interesting, because I know that was actually Amber, and I used to be colleagues at LaunchDarkly, and that was always like, a an issue we faced there, which was like, Okay, we’re gonna, we have this big marketing push around announcements and like this, if we push the docs, you know, in public, like, how would you people will see it, right?

Claire Waters 38:01 Yeah, yeah. So that is, like the one trick is, is for announcing new things is, we have to kind of be a little careful about the timing of putting up a

Brian Rinaldi 38:09 Yeah. Makes sense. Yeah.