Latest / The Not-Boring Tech Writer / Kate sounds off on making things better
Transcript
- 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! Kate Mueller: [00:00:28] Hello, lovely not-boring tech writers. I'm Kate Mueller and this is one of our solo episodes where I share things I'm thinking about or working on or both. I'm recording this episode in early July, in the midst of Wimbledon, the World Cup drama, and U.S. semiquincentennial celebrations. Try saying that one five times fast, especially when you know it's being recorded to live forever on the internet. Kate Mueller: [00:00:54] So first, my progress update. I've spent the last month doing a fun hodgepodge of tasks. Much of it was spent pairing with one of our developers, Sue, who's been building a SCIM integration with Okta to handle author provisioning in KnowledgeOwl, and I've been helping test that integration and working on the documentation to go with it because that's a requirement to submit it to the Okta Integration Network. And we've had that fun process of both figuring out how to make all those pieces work and then figuring out what Okta's requirements for the documentation to accompany it are, and submitting all of that, and then getting feedback on our app and our config guide, and then trying to meet all of the requirements and understand the feedback so that we can, in theory, get our app officially approved and added to the Okta Integration Network. As you all know, working with third party integrations and making sense of someone else's docs while you do that to try to figure out how to write your own is always a bit of a rollercoaster. And so I'm really glad that I was working with Sue on this. We got to learn and grumble and debate what our user base needs, and then celebrate our progress together. And hopefully by the time this episode airs, Okta will have accepted the integration and it will be live in their catalog. Fingers crossed. Kate Mueller: [00:02:20] I've also been continuing to chip away at article editor updates. And actually, just a few days before I recorded this, our other developer, Pete, released a number of UI improvements to the new article editor, including a total redesign of the versions interface, partial redesign of the editor toolbar itself, and the addition of a few new little editor features as well. So this effectively removes my last excuse for dragging my feet on updating the versions documentation. It also gives me a bunch of new features to document. It will also mean I need to revisit some docs that I had already updated, because we've now again redesigned some elements of the UI, both with the editor toolbar as well as some of the options and layouts in the upper half of the editor. So I've got my work cut out for me. Normally I would give you sort of like counts on what I've done and what I have left to do, but to be perfectly honest, I don't have numbers for my updates this month, and I haven't yet fully gone through the huge list of changes he rolled out to figure out how many pages I also need to revisit. So right now, it's like an unknown, amorphous. It's probably like a hundred articles. I don't know, but I'll get there. Kate Mueller: [00:03:40] I mean, the underlying thing about this is that it's a great problem to have in documentation land, because it means that we made a lot of really great changes in the editor, and it feels like it's getting really close to its final state, and that's exciting. I love using it. I actually really love the versions redesign because I was really struggling with the previous new design. So I'm kind of all for these changes. And now I'm pretty excited to work on those docs again. I'll probably prioritize the new editor features first, since those will be great to showcase, and then go back through things that I either need to update again, or the versions documentation, which I'd been holding off on because I wanted this redesign out first. Kate Mueller: [00:04:23] But the flip side of that is that I also started to get burnt out on the article editor updates because I've been plugging along at these for several months now. And so part of what I did this month was I used one of my favorite strategies for managing burnout, which is something I like to call productive procrastination. So for me, productive procrastination is I can't work on the thing that I know I should be working on, and so to procrastinate from doing that, I'm going to work on something else that still feels really productive to me. So I keep a big list of potential productive procrastination tasks. In this case, I didn't necessarily pull from that list. I took a look through my tasks and found something that hadn't come to the top of the priority list yet. It was totally different from what I'd been doing with the article editor updates, and it was something that would feel really good to complete. And so that was my productive procrastination for the month. I put a few hours toward that instead of the article editor updates. [00:05:26] So in this case, my productive procrastination task was around our syntax highlighting. I use Prism for code syntax highlighting in the Support knowledge base, and I like to, but often don't remember to periodically check to see if they've released new plugins or other features that might be useful for us. And so I was like, oh, maybe I'll just check this. Maybe this could become a task. Maybe not. And when I checked things out this month, I discovered that they had released some totally new to me plugins. And as I was going through the process of updating our JavaScript and CSS to make sure that they would handle that, I realized that I had never documented the process for updating our usage of Prism before. So I took this as an opportunity to write docs and test them as I went on that part of it. Kate Mueller: [00:06:17] So my productive procrastination choice has led to a whole bunch of really great things. I mean, first, it got a periodic task that I often avoid off of my list: the act of reviewing and updating Prism. I should probably be doing this on a quarterly basis, and the truth is that I do it like once a year when the spirit moves me. Second, it created an artifact that will make this a faster and smoother process in the future, which is my internal documentation on how to do those updates. I think just having that alone will likely make it faster for me to do these and make me less likely to procrastinate on them. But third and most exciting of all, I discovered that Prism now has a plugin for loading code samples directly from files, and you can specify line numbers or ranges from those files to display. And since a lot of my code samples are pulled from a few common HTML templates and CSS sheets within KnowledgeOwl, this is a huge game changer for me. Previously, I'd been manually copying and pasting segments of those files into my pre-formatted code blocks in our documentation, and keeping them all updated was one of those tasks that caused me ambient stress because I knew that I wasn't staying on top of it everywhere. It was one of those things that I just kind of let slide sometimes. It's also a bit of a tedious task just because I'm documenting KnowledgeOwl in KnowledgeOwl, and the HTML templates that I'm referencing have some merge codes that get populated as the page renders. And so I couldn't just copy and paste those code blocks directly in because the merge codes would render instead of displaying the code. So I had to take a little extra effort to comment them out so that they would properly display in the code blocks. You know, just like a little bit of extra tedious stuff. Kate Mueller: [00:08:14] And with this shift to loading my code samples directly from files, first of all, I can reduce my manually added samples significantly. I'm ballparking that it'll probably be by at least 50% that I will reduce those manual blocks, and the blocks that remain will be page specific: you're walking through this, here's how you do this customization, here's what the code would look like after you've done that customization. Those will be the bespoke components that will still be manually added. But the original reference of here's where you add it into the code itself, that'll reference that common file. Kate Mueller: [00:08:52] So that's really great. But also in my testing, the KnowledgeOwl merge codes that are in those files don't render on load, so I get to avoid doing the extra manual formatting for each sample to ensure that the code itself loads instead of the rendered merge code. And that, for me, has been one of the most tedious tasks. So that's fantastic. Plus, I can now use KnowledgeOwl's built-in file references to track all the places that display that HTML or CSS file, and then when we release updates to those templates in the future, I can use that file reference list as a punch down to make sure that line numbers or ranges are still accurate, that there aren't any other changes to those bespoke customizations. And what I've done at this point is I've already uploaded my files for each of those templates, and I'm working my way through pages that reference them to replace the manual code blocks with these file fed blocks instead. So I'm taking one template a week and doing that work as a productive procrastination. And since a lot of these pages also do reference those bespoke customizations, it's giving me an opportunity to review those samples to identify places for further improvements or other optimizations. Kate Mueller: [00:10:20] Is this the most important thing for me to be doing right now? No. Probably not. The article editor is, but it's the middle of summer here in the US, and burnout is a real thing. And it feels really good to still be getting meaningful things done, even though they maybe aren't getting done on the most important thing all the time. And that kind of break from the article editor stuff has made me way more excited to return to it. And now that we've released this big batch of improvements in the article editor, I have a lot of work there, but I'm a lot more enthusiastic about approaching it. So I think I picked the right time for my productive procrastination. And all of that is to say, it's summer. A lot of us are really burnt out on a variety of things. I encourage you to identify some good, productive procrastination tasks in your own backlog, and give yourself permission to use them to fill those burnout times, or use them to fill those late afternoons when you really don't want to start the next big project, but you still want to make progress on something. That's what productive procrastination is for. Kate Mueller: [00:11:31] And finally, in the last month, I've, of course, also been reflecting on my interview with Vladimir Izmalkov. One of my favorite pieces of this interview was discovering how closely aligned Vladimir and I are in wanting our documentation to make someone's life better, on all the ways that taking complicated things and making them thoughtfully simpler can be a net positive for the world. Or, as Vladimir so beautifully put it, “making them simpler for people to enjoy them with less effort and less time spent.” I really like the combination of the idea of enjoyment, as well as spending less time and less effort. This is kind of a subtheme of this podcast for a long time that I think it does help make the world a better place, good tech writing, and it always makes me smile to discover another tech writer who's had wildly different experiences from me, who still approaches the role with this same mindset or a variation of this mindset. Kate Mueller: [00:12: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:12:57] I would also strongly encourage you to go check Vladimir's talk on the tech writer's skill tree, particularly if you're currently job hunting or thinking of shifting roles in some way. The titles and the graphics for each class of writer are entertaining, and I think there's huge value to spending some time thinking about what class of tech writer you are, what your skills in each area look like, and how those map to the roles you're looking at. I'll toss another link in the show notes to that talk if you didn't check it out after the last episode. Kate Mueller: [00:13:29] Although I couldn't have planned it this way, his episode is a really solid complement to Heather Zoppetti's episode, as they're both a bit about taking existing skills and finding ways to make them relevant and salient to new roles. And in our current economic reality, I suspect a lot of us are feeling like we at least need to have a backup plan, an updated resume, or some other escape hatch. So for me this month, I'm hoping to take stock of all my idiosyncratic skill sets to figure out which ones I feel expert enough in and where I have gaps that I want to address. Maybe I'll even come up with a quirky name for my class of tech writer, although I'm really bad at naming things. So if you have suggestions for what you think my class of tech writer is, send them my way. And who knows, maybe they'll make an appearance in a future episode. But I hope that you, too, can take a little time this month to reflect on where you're at, where you'd like to be, and where to level up your skill tree. Oh, and that awkwardly rhymed. I didn't plan that. That just happened. Kate Mueller: [00:14:33] But I've had job searching and pivoting on my mind a lot lately, because I have several close friends who are in the thick of the hunt right now for every reason in the book. Some of them are burnt out, some of them have been laid off as the companies that they're at struggle or quote unquote, replace people with AI. Some of them are just at the point where they know it's time to find something new or are juggling other life events, right? We all know that looking for a job is a job unto itself, and it's often way more stressful and taxing than working. I know that these are issues which are top of mind for a lot of folks, and I wanted to take this solo episode just to share a couple resources that may help if you're somewhere in this boat. The first of these is a job board Google sheet called Good Documentation Jobs. It's a board that's been created and freely shared by senior documentation engineer Adam Pugh. It started as a personal project, as he was looking at jobs, he was wondering whether there were more technical writing and documentation jobs out there than what he was seeing on the major job boards, and he ended up going from creating what initially felt like a jobs feed board to something more like a jobs classification board. And that shares roles with a full range of titles, some very unusual that you wouldn't expect, whose core substance still falls within the tech writing sphere. Adam maintains the sheet and updates it regularly. It is free to access to the public. He's also written some posts about the process behind creating the board in his Substack. I will link to both the board and his Substack in the show notes, in case you want to go check them out. And also, Adam, thank you so much for letting me share these resources. We're definitely in a time of flux and change in our industry and one of the things I find most excellent about this sheet is its ability to surface roles with titles I wouldn't have thought to search for. I'm also a bit of a spreadsheet queen, and it's a lot more calming to me to review job postings in this format than browsing or searching sites like LinkedIn or Indeed. And most of all, I really love and appreciate that Adam originally undertook this just as a personal job hunting task, and then decided to share it with the entire community. This is part of what makes our community so awesome in my ever so humble opinion: we're willing to share this stuff. We're willing to have spent the time on it to solve it for ourselves. And then instead of hoarding that, we potentially share it out to other people. Kate Mueller: [00:17:18] In a similar vein of wanting to help serve the community as people look to hire or find new work, Chad, our podcast head of operations, and I have been quietly working on a new program, and I'm going to share that with you today. So you are a not-boring tech writer. So am I. So are a ton of our listeners. And one of the things I've been most focused on with this podcast is trying to create space and community for all of us. And generally, it feels like we've been very successful at that. But for me, it hasn't quite hit some of the connection points that I've wanted, although I've heard from a bunch of you about how much you appreciate the podcast, it is still a pretty one way connection where I talk and our guests talk and you listen. And obviously that's kind of what podcasts are. But at the same time, I am seeing a lot of very talented, experienced folks looking for work. And I've heard from a lot of folks with open positions that when they post a job and then get overwhelmed with applicants from LinkedIn and Indeed and other job aggregators, that wading through the tsunami feels overwhelming and it's making it hard to hire also. And I don't have a magic wand I can wave to fix this for everybody, but I do believe that it's kind of on each of us to try to make a difference where we can. And so we're trying something new with the podcast to try to help connect those of you who are looking to hire awesome technical writers with a pool of awesome technical writers. So think of it as your entry into an elite group of not-boring humans who all share the commonality of listening to and following this show. Y'all are VIPs as far as I'm concerned. Kate Mueller: [00:19:04] So internally we've been calling this The Not-Boring Job Opportunity Shout Out program. That's an incredibly unwieldy title, so officially, we're calling it the Hire a Tech Writer program. And basically, it's our way of using the podcast to pass along job opportunities from not-boring listeners like you who might be hiring, that seem well suited to other not-boring listeners who are looking to get work. Maybe that's writing roles, maybe it's support or CX, maybe it's some title that we've never heard before that maybe just started showing up in Adam's jobs spreadsheet. So the way the program works is we will be doing short spots in the middle of episodes with job opportunities. We'll only pass along opportunities that seem like a solid fit for our audiences. This is not like we're going to start spamming you with a thousand ads for services you don't want. So if you're looking to hire a not-boring tech writer, or you're looking to hire someone who at least has some not-boring tech writing skills, the way the program works is you'll pay us a nominal fee. And then I will share your opportunity here on our episodes, and we will also share it on our social media accounts. Kate Mueller: [00:20:21] So we will drop it in either before or after the KnowledgeOwl ad. That's generally in the middle of the episode, which is considered a mid-roll ad. If we were a heavily monetized podcast, that would be the most expensive spot to run an ad. And with that ad run, you will get access to a small but fierce and dedicated group of listeners who just might be exactly the person you're looking for. Our goal here is just to connect awesome candidates with solid opportunities where you know you're already philosophically aligned because you share the common bond of finding this show to be worth your time. So if you have a job opportunity available now or coming up and you want the advantages of sharing it with our group of distinctly not-boring listeners, please head to thenotboringtechwriter.com and select Hire a Tech Writer. You can reach out to us for more details and information about the job opportunity that you want to share, and we'll work with you to share it out. Couple disclosures: there is a fee associated with the service because sadly, that's the world we live in, but we're keeping it fairly low. We aren't doing this as a podcast monetization strategy. The fee is just to compensate our team for the time it takes to do all the backend logistics, to get things recorded and formatted and shared with our audience. And I guess this is also a heads-up to you as listeners, that you may start hearing these occasional postings, and I hope that they feel like a good fit for you. And if they appear, please give us some feedback about it. [00:21:51] I'm a firm believer that there's a craft to the work we're doing, a craft that no automated tool is ever going to truly replace. The skills we have are meaningful and useful. We distill complex things into simpler terms. We center empathy and humanity. We think about how our readers or our viewers or our listeners or our users are best served. What would make their lives better? We facilitate contributions and reviews from very smart people who might not be able to write their way out of a paper bag, but they know a hell of a lot about the things they're experts in. We automate where we can. We write guides to help ourselves or our contributors and reviewers. We do the tricky work of defining and enforcing helpful and realistic standards. It's not necessarily the most glamorous work most of the time, but it does seem like a lot of us enjoy doing it. And so if you're looking to work with someone with a similar ethos, send us your opportunity or ask us for our press kit so you can lobby your hiring manager or your HR department to send it to us. We all do better when we all do better, and we need to look after each other. This is an experiment as most of the things on the podcast are, and we'll see how it goes. Maybe this isn't a thing anyone wants, in which case we'll phase it out. Maybe it will prove useful. But seeing these struggles and knowing that we act like a small community hub, we felt it was worth trying it to see what happens. Maybe this is one of the ways we can make things better, and maybe not. We'll find out. Anyway, as always, if you have ideas for topics or guests, if there's a bit of the tech writing world that your life would be improved by hearing an episode on, or if you'd just like to tell us what you're getting out of the show, please message us on LinkedIn or Bluesky @thenotboringtechwriter or email tnbtw@knowledgeowl.com. You can also hit up thenotboringtechwriter.com and select Suggest a Guest to recommend yourself or someone else as a new guest. [00:24:04] 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.