Latest / The Not-Boring Tech Writer / Documentation as a creative endeavor with Nick Graziade

Transcript

Documentation as a creative endeavor with Nick Graziade · The Not-Boring Tech Writer

• Kate Mueller: [00:00:04] Welcome to The Not-Boring Tech Writer, a podcast sponsored by KnowledgeOwl. Together, we explore topics and hear from other writers to help inspire us, deepen our skills and foster our distinctly not-boring tech writing community. Kate Mueller: [00:00:19] Hello my fellow not-boring tech writers. I'm Kate Mueller and today's guest I'm really excited to have on the show. Today's guest has been a longtime guest blogger for KnowledgeOwl, which is how I first came across his work and knew that he existed. He did a series of blog posts both on single sourcing and then a whole bunch of stuff on grammar. I was like, "This is somebody I feel like I align with on a lot of things." I was very delighted when he said yes and agreed to come on the pod, so I would like to welcome to the not-boring tech writer universe, Nick Graziade. Nick, welcome to the pod. Nick Graziade: [00:00:54] Thank you for having me. Kate Mueller: [00:00:55] Thank you for being here. Just to start us off, to give the audience a little bit of knowledge about you, can you tell me what your tech writer villain origin story is? Nick Graziade: [00:01:06] This one I have to tell you in two parts, because there's a subversive one that snuck into my brain, and another one that emerged later on in life. Kate Mueller: [00:01:17] A two part villain origin story, you're a complicated villain. Nick Graziade: [00:01:20] I try to be. I'm a complicated person with simple tastes. The subversion here, the thing that snuck into my psyche, started when I was about 3 or 4 years old. I don't have many memories from that, and I don't have many memories from the 1980s in general, but I was a little toddling one in the 1980s, and I got my first Lego set when I was that age. I remember looking at these instructions and I thought to myself, "Wait a second, I can build something without having to go through the complicated steps of actually narrating how to build this." I see these pictures and they tell me how to build something? That's brilliant, that's amazing. It became this massive dedication to the world of Legos and Lego instructions. I actually saved all my Lego instructions because I was like, "I'm going to build this again someday. I swear to God, I'm going to build it again someday." It never happened, it never honestly happened. But I was enamored by these documents, not really knowing what they were aside from, this is how you make spaceships or castles or what have you. Kate Mueller: [00:02:35] A fun side fact, I also have a huge Lego background, and I am the person who both saves the instructions and takes them apart and rebuilds them. I do this even as an adult now. I've changed into the architectural series so it feels age appropriate, but I totally do this on a regular basis. I'm wondering how many tech writers have that Lego tie-in. Nick Graziade: [00:03:02] I feel like a lot of us do. The fact that Lego Digital Designer, which is this software platform they created, they copped it from an independent Lego marketplace called Bricklink, which they acquired and then combined all their digital designer stuff into this massive, wonderful little sandbox that you can play with on your computer. I've definitely sunk way too many hours into that. The ability to copy and paste pieces of Legos was remarkable using this digital tool, because that set me into this whole cycle of creating really wild stuff that I wouldn't be able to create just due to physical limitations of what I own. So that was interesting. Kate Mueller: [00:03:48] So Lego is part one of the origin story, what is part two? Nick Graziade: [00:03:53] Lego is sifting around in my brain, living in my subconscious forever. It wasn't until I went to a conservatory, I was in music school for a year. The one thing I will tell you about music school is that you either get completely into it or it's going to kill your love of music. And that's what started to happen to me. It started making it a chore, and not a chore in the way people think. Because I was the guy who loved music theory and all the complicated, wild stuff associated with that. I met my wife in a music theory class. There's a lot of stuff that's really nerdy in music that I really love, but I was out of place there. I was one of 2 or 3 jazz studies guys amongst a bunch of classical students who could not get enough of things like Brahms. I love classical music, I actually am a classical musician as well, but that's not what I was studying. I was studying something very specific, I really wanted to focus on that one thing, and it started making it so formulaic. It just felt like it robbed the passion from it. To that end, I said, "Well, I got to do something." I remember I was taking this one class and it was on electroacoustic music. Now this is, for lack of a better term, Synthesizers 101. We're talking about another 80s reference here. We're talking about the kind of synthesizers that you'd hear on a Duran Duran record or something like that. I became enamored by these things, too. They were like building blocks, if you will, to tie everything together. Nick Graziade: [00:05:28] But it was how you actually used these synthesizers that really fascinated me, and what was going into them. So I learned what all the components were named, how they functioned, what they did to the sound. I thought, "This is remarkable." I knew I was going to get into the writing school where I went to my undergrad, which is kind of cool because it was the same writing school that Rod Serling taught at, if you like The Twilight Zone. So that's a great aspect of lineage to have if you're one of those people who's like, "Yeah, this is where my lineage comes from." It's not really a thing that we talk about a lot in America, but it's definitely something that, if you do like a Japanese martial art, they're going to tell you where it was founded by whomever. It's a part of the ethos of that world. I'm in the writing program and I'm thinking, "There's all this stuff on science and nonfiction here, why don't I try getting into writing about synthesizers?" And that's what led me down this rabbit hole, and I've been doing it ever since. I've been in the tech world ever since. I was graduating, and I said, "I'm going to be a technical writer." I wear that moniker very proudly. I sometimes make the common joke, 'I'm technically a writer', but we all do that at some point because it's too stupid to not pass on. You have to use that every so often. Kate Mueller: [00:06:55] it also helps make it sound a little bit less intimidating or confusing for folks. At least they get to have a little bit of a laugh. If I want to tie a common thread between the two parts of that origin story, it is perhaps that you had really good experience as a reader of technical documentation, and that opened doors for you and led you down the path of creating technical documentation. Fair? Nick Graziade: [00:07:25] That's a fair way to put it. There was an element in addition to that, of seeing it as a creative endeavor. One of the things a lot of people look at technical writing as is something that is inherently dry and inherently without passion or boring. Kate Mueller: [00:07:46] I mean, it is in our title. Nick Graziade: [00:07:48] It's almost like there's something about boring tech writers that I'm part of. That's what a lot of people get out of that, that's what they look at. I said, "No, this is really cool." Let's go back to the synthesizers for a second. I would look at these devices and say, "These are really cool, but how do I manipulate them to make a sound? How do I turn the knobs, play with the sliders, play with the dials to make all the beeps and boops really musical?". One of the things I came across, and these are really famous, the Moog synthesizer manuals are incredibly useful for that kind of thing. They explain not only how to manipulate the sounds that you have, but also why. I'll give you an example. There's a thing like an EG, an envelope generator, which draws out the way the sound looks over time. You could think of it almost like a piece of a wave, or maybe like an arc, because you could create a sound that gradually rises in volume and then steeply drops in volume. It's kind of the opposite of a piano. You hit a piano and it makes its loudest sound first and fades away. You could have something fade in and then abruptly stop. You use an envelope generator to do that. Their manuals explain how to set it up, but also why it does the thing it does. I thought that was the coolest thing. That whole justification attached to that manual. I'm not just knowing how to do it, I'm knowing why I'm doing it. That was a level of mystery and beauty that I thought a lot of manuals, a lot of documentation, was missing. It got me hooked because I could keep learning more and more and more. I'm like a sponge that way, I just want to absorb every darn thing I can get. Kate Mueller: [00:09:34] Which serves you well in this profession, for sure. You're a proud tech writer by title, what is your current role or what kind of documentation are you currently working on? Nick Graziade: [00:09:47] My current role is with a small startup company out of Troy, New York. The founders were associated with Rensselaer Polytechnic Institute, that's where I went for my grad studies. A bunch of folks there are from there. It's been around for about 6 or 7 years now. It's moving out of the startup phase, we're having a few growing pains from that. Nothing I haven't seen before. I am the lead technical writer there, and I do all the requirements documentation and the software documentation for our system. That involves a lot of database stuff, a lot of mappings, a lot of SQL, a lot of API stuff. There's a lot of hyper technical stuff going into this. Fortunately, my audience is the development team. I'm an internal-facing technical writer in this circumstance, which makes it a lot easier to communicate some of these radically wild concepts to anyone outside of the dev team. If you're not in the dev team, you're going to see some of these things and go , "What the heck is going on here? Why is he talking about this stuff? What does this even mean?" Kate Mueller: [00:11:00] But you have a very clearly defined audience and a good understanding of your audience, so it allows you to very much gear your content toward that audience's needs, which is helpful. Nick Graziade: [00:11:10] Absolutely. That's something you and I have talked about before, is writing towards an audience. What is your understanding of the people you're working with? What is the understanding of your readers? How do you adjust your needs to their needs? You have this responsibility on many levels to create something that's useful for your audience. If you don't, what have you actually created? Kate Mueller: [00:11:34] Not really anything. There's a deep philosophical, existential question there, but yes. And the audience dictates so many factors as we write. The same content geared toward different audiences can look wildly different. I feel like you and I have had conversations around grammar, but in the sense that there are different grammars that people use in different contexts and in different ways. There are some ways that come into play as you are writing content for different audiences, different experience levels, different whatever. You're providing context in a different way, you might be going into a certain level of detail. Or not, depending on who that audience is. So it's highly relevant. Nick Graziade: [00:12:29] You hit something on the head there really well, and that's the concept of using different grammars for different audiences. This isn't just something you see in writing either. This is something you see everywhere. It's fundamental to communication at the end of the day. Be it artistic, professional, political, spiritual. All modes of communication require a language that everyone speaks commonly, so you can abstract that to the highest level possible. That said, when I'm looking at a certain audience for technical content, I do have to know what assumptions I can make about them and which ones I can't. For example, I can assume that most people in this day and age know how to use a typical interface. People can use a keyboard and a mouse, so I don't have to say the mouse is the thing that has the little tail attached to it that hooks up to your computer. I don't have to explain what a touch screen does. These things have entered the cultural zeitgeist and have become common enough that we already have those mappings in our head as to what they are. There are other things that are heavily jargon-ated that I would never say to a sales guy. For example, the guy who's going out and selling the product. Nick Graziade: [00:13:51] That is a skill set I do not have, and it's because I don't speak that language. It's not that I couldn't, but I've never taken the time to cultivate it. It's not the one I'm interested in cultivating either. Everything has a different language that you work with. I'll even go back to, and I'll probably do this half a dozen more times, another musical example, which is something I do all the time. If I'm playing a jazz tune and I want it to sound a certain way. I want it to sound like I'm playing jazz bass, which is actually what I studied. The fact of the matter is that there is a vocabulary of sounds and lines and patterns and things that the rest of the ensemble is going to expect. Because, mind you, this is improvisational music. They expect me to fill this specific role, and if I go wildly outside of that, I'm actually not doing my job. Nick Graziade: [00:14:49] A lot of people will tell you that jazz can be whatever you want it to be, but it can't. Because yes, on one level you can say that, but on another level, if I stop doing the thing you expect, I've broken the agreement that we had on the language. It's very much like Wittgenstein's language games. He had this whole concept that if we're playing the same language game, we can talk to each other. If we're not, or we are playing by a different rule set, it's going to change everything. If I'm trying to play a bebop tune, something in the style of John Coltrane, and suddenly there's a guy who's taking a solo and it sounds really like Django Reinhardt and French jazz music, a completely different set of vocabularies. It might work, but there's more of a chance it won't because people won't expect that. You can actually hear this on old jazz recordings, too. Like when Coltrane himself would bring in tunes that broke the expectation, you could even tell some of the keyboard players and bassists are having trouble keeping up with the harmony, because it's so radically different from what they expect. It's not the same language. Kate Mueller: [00:15:56] It's not that it's not possible, but it creates a whole lot more work for everyone involved to bring those pieces into alignment and figure out where they stand. Which does translate really well into the writing world. Because if you're straying too far outside of the content type that you're focusing on, or your audience, or some other aspect of that genre, it's going to be jarring. It's going to be uncomfortable for somebody engaging with that. In a way that, if you're predictably structuring things, if you're using language in a consistent way, if you're styling and formatting things in a consistent way, those things, through their predictability or familiarity, reduce stress. They make that a much more pleasant end user experience. If you're bringing in too many different things from too many different places, you're just amping up the ambient stress and making it harder for somebody to get what they need out of that and leave feeling successful and competent. Nick Graziade: [00:16:56] That's a really important aspect of technical communication that a lot of people who go into technical writing specifically don't think about the entirety of communication attached to this. Some people think it's just going to be writing about the content, and on one level, that's true. There's another factor here, that we can look at things like contrast versus repetition. Like you said, if you have a uniform way that you're communicating something, you're always using this term. You're always using this particular demarcation in your text for an interactive screen element. I'll just use a UI example. If it's a button that you click and you always highlight it, and you never say the word 'button', you just say 'click save to save' or 'to finish' or what have you. That's very clear. Then if the next sentence says, 'click the cancel button', you've already broken that expectation. It goes into a sense of parallelism that you want to establish throughout. Because then when you break it deliberately, you've actually got more attention. When you see one of those little text warnings that's big and red and flashing, that is a huge amount of contrast to regular diagrams, figures, step by step instructions, all of those things. The contrast itself becomes an element of the communication as well. This is one of the things I see with the developers I work with a lot. They will often write the way they speak to each other, which is both full of jargon, but it's also full of certain developer specific vernacular. Nick Graziade: [00:18:34] It's full of those changes that I just talked about. When you describe something to someone, you're going to use a lot of little bits of meta discourse to go from point A to point B to point C, these are those little connecting words. Then when I get writing like that a lot of the time, I go through a lot of it and remove those. Not because there's anything necessarily wrong with the way they communicate, especially if somebody was reading it out loud to me, but because it creates a certain inconsistency within the document. Oftentimes I'll see something where it does say 'click the X button and then do the Y function', or 'select z and then click z'. Any manner of verbs to interact with things, those can really screw up your user because your users are going to be looking for specific cues, and they're going to be looking for specific non-verbal things. I say non-verbal even though we're talking about writing, but it's kind of the same thing. Because people are looking for cues within the text to simplify it, to reduce their mental load. Right now in the world in which we live, a lot of people have a reluctance to go through and read every single line of a text. They're looking for an answer, they're looking for something consistent. If you start breaking all those mappings, especially if you have a bunch of articles in a knowledge base, and each of them has a different format or a different setup, if they're all radically different, if you have 20 articles and they're all completely different than one another, you've really messed with your users' expectations. Nick Graziade: [00:20:15] They're not going to be able to follow these things. If you have 1 or 2 different formats that you use repeatedly, and they have a nice contrast between the two of them, it's going to be easy to map back to the same things that you're used to. We do it all the time with sounds. For example, one of the most famous sounds in computing history was the 'You've Got Mail' or the classic door opening or door closing sounds that you would get in a chat room, particularly the old AOL chat rooms. Those mapped to things we expect to hear in the real world. Well, maybe not 'you've got mail', that would be kind of weird. But a door opening and a door closing, I know someone has physically entered a room or at least peered in, in some capacity. Having existing mappings that people use all the time is really helpful for communication, so why not tap into that? Why not use that? There's definitely a lot of psychology that goes into this, but it's an important psychology because it forces you outside of some of the barriers that prohibit communication and the ability to think of new things. That's another thing I'll bring up, maybe when it's a little more opportune. Kate Mueller: [00:21:22] I feel like you're touching a bit on both style conventions and documentation, but also anything that would trigger a visual cue. Whether that's visual assets you're using, formatting choices about headings or bold or italics or other things like that. Am I summarizing that okay? Stylistically, we want to be presenting text in the same way consistently. We train people on how they should be reading our documentation and what it's safe for them to expect from our documentation, while we're also thinking about visually speaking, that we are highlighting things in the same way every single time, or formatting things in the same way so that it becomes predictable. So that when we break the rules, we might add a call out, an alert, an admonition, whatever you might call that in your docs, that it actually has power because they're used to the consistency. Then when you break the consistency, they pay more attention. Nick Graziade: [00:22:24] Absolutely, that's a really good way to put it. This was something I would always tell people when I was teaching writing classes. It was particularly useful for younger students, but also for ESL students. I've worked with a lot of English second language people. One of the things that I felt was really important to hammer down pat into people's heads is, you can break any rule in writing you want to, but you have to be able to justify why you're breaking that rule. A lot of people I have worked with in the past, particularly people who had focused very heavily on poetics rather than rhetoric or communication or psychology, people who focus more on poetics or creative prose, there was a sense that, 'I can do whatever I want to because it's my piece and there are no rules to work with'. That's actually more restrictive on some levels, because you get into this point where if there are no rules, I can do whatever I want. That's really hard to come up with something just to begin with. You're going to have the tacit rules of grammar and syntax that you always have attached to the language you work with. But if you haven't done something deliberate with it, or you haven't made an effort to understand what you're doing, it comes off as sloppy sometimes. Nick Graziade: [00:23:54] I've seen this, I've considered it many times to be the difference between good writing versus great writing. I know that this guy is writing a poem in iambic pentameter. Very strict, everybody who's studied Shakespeare at some point in their life knows way too much about iambic pentameter. But then what happens if you reverse the iamb and you have something else, or you have something that is suddenly trochaic or any of the other stress patterns? It's just one word, and it's just one place in the whole 14 lines that you have to work with. That's designed to highlight what you're doing. If you didn't know you were doing it, you might get away with it. But if you use it to emphasize something, particularly something that's a dissonance in your narrative, that's way more powerful than using a really advanced word or a really wild other thing. There's so many ways to go about this, and when you deliberately take a rule that you know, that you've practiced and you've worked with a lot, and break it for effect, for a reason, you've created a deliberate or intentional dissonance. That's a really powerful communication technique. Kate Mueller: [00:25:17] It's an interesting point about the utility or the underlying purpose of the documentation, that technical writing really does depend on that dialog. You write a novel, you probably have a period where you're getting feedback, you're getting reviews, but then you publish it. It's out in the world, it's done. You never touch that novel again. Whereas tech writing, you are constantly updating documentation because you are documenting a thing that is not static. It's constantly changing, it's constantly evolving. Whether that's a product, a series of processes, whatever that might be. You don't stick a pin in it, and that's the thing you document and then you never have to touch it again. You are constantly making changes, which means that the feedback loop is an inherent part of that, because you need to know if the changes that you've made to address the changes to the actual thing are still meeting people's needs. That they were structured in the right way, you covered all the stuff that they cared about and that you did it in a way that was clear and easy for them to follow. That makes the genre different, because you have that ongoing evolution of the documentation that never finishes. It's never done, you're never like, "I'm finished documenting that product. Never have to touch that again." Nick Graziade: [00:26:41] That's not going to happen in most of the tech writing world. It lends itself to a little bit of my own personality, because I don't really believe in permanence in any sense. I think everything is transient in some capacity. If you look at Mahayana Buddhism, they have this sense of dependent origination. Everything is caused by something else. There's always a causal chain that causes A to B to C to D to E, and so on. We bastardize it in the West and call it dharma and karma because they're cool terms to use. But it's a lot more complicated than that. There's an intrinsic sense of this non-permanence or this nonbeing that I really like about ever evolving documentation. On some levels, it makes parts of my life very difficult. It's really hard for me to write a song or a short story or something that I want to keep around because I'm like, "I could revise that, I could change that." Maybe that's why I'm attracted to jazz, because it does have a level of dependent origination, in this circumstance. Yes, I have a structure I can work in, but within that structure, I have a lot more freedom to create something that's not permanent. Nick Graziade: [00:27:54] Likewise, and maybe this is a weird thing for a musician to say at least in this day and age, a lot of people really love recording. They love recording music, they love creating a product like that, and I don't really believe in that necessarily. It's great for the people who want to do that and take great pride and enjoyment from doing that, because that's a subjective experience, and I'm actually happy for people to have that subjective experience. For me, it's much more like theater, like a live theatrical thing. The act of performing it and the ephemeral nature of some of these things makes it have a certain level of beauty that I don't think you can always capture permanently. Because I have that baseline philosophy in my head, that ideology is something I recognize within myself and something I'm aware of. I'm fully aware that this is a thing that I believe, that I practice. I can understand the contrasts with it. I have studied the dialectic of what I'm actually doing. I have had conversations about what I'm actually doing in these circumstances. But for me, that level of impermanence helps my documentation because I'm not so married to it that I can't change it. Kate Mueller: [00:29:09] Folks who struggle being tech writers, the profession does lend itself a little bit to perfectionism. I know a lot of writers who struggle with perfectionism, but you end up being a bit more successful in it if you are able to view it as a constantly evolving set of documentation, as a thing that's naturally going to become stale or outdated or need updates. That you don't get deeply invested in it having already been perfect, or even having the idea that perfect exists in the documentation. It's easier to navigate that when you view it as a thing that's always going to be in flux. That there is no permanent desired end state, that it is actually the fluidity of it that is the appeal. Maybe that's a good point for us to take a break, speaking about impermanence and not thinking something is done, so we will be back shortly. Kate Mueller: [00:30:07] This episode is sponsored by KnowledgeOwl, your team's next knowledge based 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:30:30] We are back from the break. I want to pick up on a thread from just before we took that break, which is that idea of recognizing that documentation has impermanence inherently in it and how we manage that. I want to get down to brass tacks on this. Let me use my own work as an example here. I am both lead writer, but also largely a solo writer on the documentation that I work on. Which means that I am constantly juggling this giant backlog of work and making decisions about how I prioritize what I should be working on, and sometimes undermining myself in making a different decision about what I should work on. There's always that sense of stuff being in flux and trying to make decisions about what I'm doing and managing that. I'd really love to pick your brain on how you manage documentation in that way. How do you make decisions about when something is due to be updated? How do you decide when it's done, or done enough to move on to something else? Nick Graziade: [00:31:38] There's a couple metrics I can apply to something being done enough. One of those is if I were to take a look at it, read it through, can I follow the process? Can I execute the thing that I'm trying to do from this procedure that I've documented? Do I understand what it's supposed to do? That's a pretty safe bet most of the time. It may not be perfect. It may not be as precise as I want it to be, but if I were to give it to somebody, I can get feedback and they can say, "Yeah, I can do this from this." They might say, "Can you change all these other things?" Yeah I could, but I probably won't at that point. Just because we're looking at something that I've already brought to a point of temporary finality, and any other changes would be more cosmetic. Granted, if it's a fundamental change like, "By the way, you forgot step seven", that's a big deal. But if it's something more cosmetic or preferential, somebody's got a subjective dislike of using the second person imperative form or something like that. Kate Mueller: [00:32:53] So it needs to be a complete set of steps, complete unto itself. And it needs to allow somebody to actually do the thing, whatever that thing might do. Nick Graziade: [00:33:03] This comes back to something we had talked about a while back, not in this session, but previous. To every document being page one, every point of entry being a thing that you can go into, look at it and say, "I can do this thing that I have to accomplish from what this technical documentation is telling me", and then being able to exit at that point. This is a really important thing that I've found on top of that, that has to do with hierarchy, but I'll get into that after I give you some more stuff that I use to determine when I should go about revisions. A lot of times I'm restricted to my cadence based on what the development team is doing. They're working in sprints, they're using a fully agile process now, which is fine because I'm also the administrator of our Atlassian products. I'm the guy who's running Jira the whole time too. I see when their stuff is done. I control the workflows, I design the workflows actually, trained on them and had everybody going through them. So that gave me a leg up on some levels to know when something new is coming my way. Nick Graziade: [00:34:18] It's most difficult when those changes become unpredictable. If we're working on a regular two week cadence, I can pretty much get a sense of what volume of things I have to work with. When suddenly somebody says, "By the way, production is failing and we spent a week troubleshooting it", that's going to change the volume. Sometimes, for me, it's actually much less because they didn't develop as much. Sometimes it's much more because we need to track every little thing we did, every troubleshooting step. Every option that we considered, every parameter we tweaked, every single rock we upturned and flipped over to see how many worms were under it, that is something we sometimes have to document too. That's where it becomes the most difficult. If I expect something's going to change, I've built that in. If I don't expect something's going to change, I'm still going to build in a revision cycle. Most of my documents I have a quarterly revision alert that comes by and I'll look at these things and I'll say, "Has anything here changed? If not, okay, cool. Reset it." If something has and I just haven't caught it. Kate Mueller: [00:35:30] So you're doing a combination of 'just in time' updates based on those two week sprints, but then you also have the quarterly review where you're peeking in to be like, "Did something slip through the cracks here that I need to deal with?" Nick Graziade: [00:35:46] Yeah, absolutely. Kate Mueller: [00:35:48] And during your two week cycle, are you writing docs about the changes that are happening in that two week cycle? Or are you staggered so you're basically documenting what happened in the previous two weeks? How does that work for you? Nick Graziade: [00:36:03] It's a little bit of both, and it's a little chaotic right now as we transform ourselves from a startup to a more mature organization. We haven't codified a lot of those processes, so that's what I'm doing right now. Believe it or not, I'm actually sitting down and auditing a lot of the things we do to make sure we understand how we got to where we are. Development has slowed down a little bit, not detrimentally, but it's slowed down as people adapt to new techniques and new ideas and stay more focused. They're more focused on specific granular things. Which on one hand would drive me nuts because I like to know everything about everything, but on another hand, it has helped the developers stay focused and has given me the opportunity to work on some of these audits to understand, how does this service work? How does this API work? How do these things actually interact with each other? It's not just writing these things, I've created tons of UML and C4 diagrams to make sure everybody understands every little bit of what's going on. Kate Mueller: [00:37:16] How large is the team for you at this point? Nick Graziade: [00:37:18] The team right now is about 40 people, and that's for an organization of 60 people. The development team is massive. Half of them are offshore. I work with a team in India, and I work with a couple people scattered around the United States as well. Then there's the core team in Troy. Kate Mueller: [00:37:43] Nice. That's a lot to juggle, a 40 person team. Do you have any other writers working with you, or is it just you? Nick Graziade: [00:37:49] It is more or less just me. We had another person, and what she has moved to doing is now more product owner, scrum master type things. She's taken on that role, and the way we look at it is if she's doing technical writing, it's outward facing. I'm doing more inward stuff. That's probably the best way because, realistically, I was the more technical person of the two and definitely the more experienced one. I definitely had that weird experience where she was there and a couple other folks were there, and I looked around and it was a pretty empty day. It was a Friday in the office. I'm looking around and I'm thinking, "Oh my God, I'm not just the only person who is over the age of 30 here, I'm the only person who was born last millennium." And that was weird, that was a weird experience. Kate Mueller: [00:38:34] That's sobering. Nick Graziade: [00:38:35] It was weird, I don't know how else to say it. I'll interact with anybody. I have friends that run the gamut of age from their mid 20s all the way up to their mid 80s, and that's awesome. I'm glad I get that diversity of ideas and opinions and generations and people, and we all have stuff that we love together, so that really helps me. Kate Mueller: [00:39:00] So you do divide, you're doing all the internal stuff and she's doing basically the external stuff. Nick Graziade: [00:39:06] Which isn't much, to be honest. There isn't a lot of external stuff, it's more like product management. We're working in two different streams. A lot of times what I have to do is go and clarify the software requirements. I've spent a lot of time working with the state of New York to write software requirements. Doing the requirements gathering, doing the software analysis, doing the BA thing on top of the technical writing. They're definitely counterparts in this world, and I've been on many state projects. I was on the Affordable Care Act project and made it up to lead tech writer there. I've worked with the DMV, and I've worked with energy research and development and all sorts of state contracts. There's so much requirement gathering that goes into these things because they have to follow legislation as well. They have to follow complex legislation that has dozens upon dozens upon scores upon thousands of conditionals and little bits and pieces and exceptions for every little thing you can imagine. Writing requirements that are clear and logically sound, writing business rules for that stuff, is an art in and of itself. A lot of times I'm taking those business rules and translating them into something that is technical. Nick Graziade: [00:40:31] L-statements, logical flows, things that a developer would work with. Then at the end of the day going back and looking at them and saying, "These actually reflect what we built." If we have to change it, that's another one of those cues to say, "Time to revise this thing. Time to revise these business rules here." Because those things change all the time. I've created a lot of automation and little warnings and other things that offload some of that reminding, but it's about staying vigilant because it does have to evolve. If it gets behind, especially if you have a new hire, and I've got this developer who's come over from England or something and he says, "I don't understand what this means now." It's like, I see why you don't because we neglected to update that a year ago when we changed the business rules. These are things that slip through the cracks, especially if you're a department of one. Even if you're a department of one and a half, which is what I am. But I've been doing this a long enough time. Nick Graziade: [00:41:39] Realistically, I look back and I have been doing this for 15 years now. That's a long time to be in one career path. I am very happy with that, because I really enjoy cultivating my experience and doing what I do. But it is a long time, and it's given me a lot of insight on how to stay on top of those things. I've just shared a bunch of them. Offload it when you can, stay on a cadence, have reminders, and don't be married to the permanence of it. Things are going to change, your structures are going to change. The way you organize your information is going to change, and that's going to evolve with your audience changing too. You get people who become better developers. People leave an organization, people come in, you now have a new audience. It's this very amorphous, nebulous blob of ideas and people coming together for a singular purpose, ultimately. But you get through it. And by being flexible and by not remaining so rabidly zealous towards a single idea of what documentation should be and must be, will lend a lot of credence to those changes and make them a lot easier. Kate Mueller: [00:42:57] Which I feel does tie back to your point earlier about it being a dialectic. Because a lot of what you're talking about here, in terms of how it's changing and evolving is about, we get new hires on or other people leave, and so the audience needs change. The only reason you know that those audience needs have changed is because you have that ongoing conversation. Which helps signal to you, this is something that we need to change now. The aspect of the style guide or whatever. Kate Mueller: [00:43:27] Nick, just to wind us down a little bit, I know we've had a pretty far ranging conversation, are there any resources relating to anything that we've talked about today that you would love to point people to as reference points? Nick Graziade: [00:43:43] Yeah, one of the things that will be really cool to take a look at, you don't even have to understand what it does, but I would go to the Moog synthesizer website and check out some of their manuals. Check out some of their documentation. Sometimes seeing something that's cool and quirky and weird in practice can be really useful. Kate Mueller: [00:44:03] Excellent, we will toss a link to that in the show notes. Also, what is a great piece of advice that you've been given? This does not have to have anything to do with technical writing. I just like sponging advice from people, so lay your wisdom upon me. Nick Graziade: [00:44:18] This is a bit of wisdom I learned inadvertently from my father, who I would consider to be the wisest man I have ever met. It actually ties into music, believe it or not. There's no surprises there. Kate Mueller: [00:44:29] Imagine that. I'm shocked, Nick. Nick Graziade: [00:44:32] It's so weird how rarely that comes up. Kate Mueller: [00:44:37] I feel like you've not mentioned it at all the entire episode. Nick Graziade: [00:44:41] I don't think most people know that I'm a musician, believe it or not. Kate Mueller: [00:44:43] Surprising. Nick Graziade: [00:44:44] It's pretty wild. Anyway, it was around the time I was getting into playing the bass for the first time. I had learned a song that the Beatles had written. I had a great teacher, and he would explain to me all the music theory about what Paul McCartney was doing, and I thought it was the coolest thing ever. I was like, Paul probably didn't even know that he was doing that. And honestly, he didn't. Paul McCartney can't read music, he's just that awesome. He is just that much of a genius. But I'm explaining it to my father, he's driving me into school and I'm explaining it to my father because I have a presentation on it for the music class. I'm really excited and I'm going through it and I say, "Yeah dad, he uses all these chord changes and it's this thing called the contrapuntal elaboration of static harmony, because the harmony is static, but one voice changes. Then eventually that leads into a secondary dominant into another chord." I just thought it was the coolest thing ever. At a certain point, I realized he had no clue what I was talking about. I said to him, "So dad, you didn't get any of that at all, did you?" And he said, "I think it's really important that I listen to you because it was important to you." Nick Graziade: [00:45:56] "It was so important to you to be able to share this thing that you found enlightening and beautiful." He didn't put it that way, but that's essentially the message here. "I thought that I should listen because it's important to you, and I want you to have that experience of sharing it." I have taken that to heart every moment of my life since. People will explain to me things that, I will be honest, I could not care less about. But it's not about me at that point and that's okay. That's 100% okay that it's not about me, because everything doesn't have to be about me. I don't want to sit here and talk about myself. I'd rather talk about ideas and other cool things and synthesizers and what have you. You'll learn about me that way. But if somebody tells me something, and you can see the passion, you can feel the fire in their belly is roaring, and you sit there and dismiss that person, they're going to be heartbroken. But if you sit there and listen and engage and ask them to just keep explaining, "tell me more about that", you're going to have one of the greatest experiences that you've shared with a person, because that person now has been able to share with you something they love so much. Kate Mueller: [00:47:11] They got to geek out and they got to feel like they were seen and heard, and that's a huge gift. Nick Graziade: [00:47:19] No one's experience is something you want to discount. Every single person has a different set of experiences, and we all have to look at it from the standpoint of, "I can get maybe 95% of the way to understanding what your experience is like, but I'm never going to be 100% because I wasn't you." That's okay, and that's the beauty of it. That's how our diversity as a species, as a humanity, works. That's why different writing works, and that's why different ideas work with different people, because things resonate on different frequencies. Kate Mueller: [00:47:55] That's a lovely story and an excellent piece of advice. My last question for you, since I ask this of everyone, if you want any of our listeners to get in touch with you, how would they do that? This could be professionally, this could be, "what are you doing musically?", and you'd love to have people know that's what you're doing. Nick Graziade: [00:48:14] If people want to reach out to me, I'm going to give you my email address and you can reach out that way. If you're ever in the New York Capital Region, you can look for me. I'm playing all sorts of gigs here and there. I'm a member of a group called The Mojos House Band. That's from a cafe that my friend runs called Mojo's Cafe. I am a member of a band called Twice Twice. I work with the Rensselaerville Stage Creations theater group. I am their musical director from time to time when they have musicals, because God knows I'm a wonderfully theatrical person at times as well. Kate Mueller: [00:48:52] I love it. Thank you so much Nick, this has been an absolute delight. A little corner of the philosophy club meets the not-boring tech writer. Nick Graziade: [00:49:01] The pleasure is all mine, I love you guys. It's been a privilege to continue to be part of the extended family of KnowledgeOwl. I'll be a super fan until I'm not here anymore, let's put it that way. Kate Mueller: [00:49:15] Thank you so much, we are also super fans of yours. Kate Mueller: [00:49:24] The Not-Boring Tech Writer is produced by the lovely humans at Astronomic Audio. With editing by Dillon, transcription by Alan and post-production by Been and Alex. Chad Timblin is our podcast head of operations. Our theme song is by Brightside Studio. Our artwork is by Bill Netherlands. You can check out KnowledgeOwl's products at knowledgeowl.com. 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 not-boring tech writer.