Zohra: 0:01

Hello folks, welcome to another season of Inside TechCom with Zohra Mutabana. In Season 6, we unpack how generative AI works and what it means for your TechCom workflow, from core concepts to practical use. We're going to go under the hood. It's time to adapt, create and thrive with AI. Let's dive in. Adapt, create and thrive with AI. Let's dive in. Hello folks, welcome to season six of Inside Techcom with Zohra Mutabana. I've become a little rusty so please forgive me today, but I'm super excited to have Manny on my show here. We're going to chat about what else? Generative AI and, even more exciting for me personally, it's going to be agentic AI. So with that, manny, please welcome to my show. You've been here before, but you know the drill Tell us a little about yourself.

Manny Silva: 0:59

Thanks for having me, Zora.

Zohra: 1:01

Of course, it's a pleasure always. What's exciting in your life right now? What are you doing? New things, anything that you'd like to share?

Manny Silva: 1:08

Sure. So for folks who don't know me, I am Manny Silva. Hi, I am head of documentation at Skyflow. I am also the author of Docs as Tests, a strategy for resilient technical documentation which is the new exciting thing that's happened to me where I discuss how to treat documentation as testable statements about your product behavior. Additionally, I am the creator of Doc Detective, which is an open source toolkit for implementing docs as tests, and I am a father of three. My life is beautiful, chaos.

Zohra: 1:49

I love it. Beautiful chaos and Manny, congratulations on the launch of Docs as Tests. I have been reading parts of it and I'm loving it. I hope I get to do something hands-on with it someday soon. But congratulations, and for folks, I think this is something important that I would love to share. I got to actually meet Manny in person at the conference. Yes, in San Jose. I'm always getting confused between San Jose and San Francisco, but it was in California. How about that? I'll play it safe, there we go.

Manny Silva: 2:19

And it was wonderful meeting you there. Zora, it was nice to finally be able to see you in person.

Zohra: 2:25

Exactly Likewise and we didn't get much time, but whatever time we got, this is how this particular discussion came around, and I am looking forward to learning more about agentic AI. So today we're going to be talking about agentic AI. Manny, we use, I use I'm sure you definitely use agents. With ChatGPT, I'm using Copilot at work. I've been creating agents. I'm getting, I guess, used to them, trying to configure them Without prolonging this. Are agents the same as agentic AIs?

Manny Silva: 2:58

It depends on how you define the term. Broadly speaking, agents and agentic AI are the same thing for most people, and to define what those are, an agent is a generative AI application that can take actions based on the tools given to it. Now that is the broadly accepted term for an agent, which most people are already using today without realizing it. Chat, gpt is an agent. The cloud web interface is an agent because they can search the web, they can go out and summarize things for you, like they can fetch information you, if you hook them into various apis which are different than the underlying loms, which are gpt 4.1 or whatever. The current model is claude 3.5, sonnet. Those are the underlying models, but applications built on top of them are the agents. An agentic ai, by some people's definition, is effectively an AI that knows how to go about taking action without prompting via tools. But I think that's a highly theoretical definition and I haven't seen one of them myself. So for all intents and purposes, an agent is the same thing as an agentic AI.

Zohra: 4:27

Okay, thank you for simplifying that for me. I don't feel as intimidated now talking about them, especially agentic AI. At the conference that I attended, there was so much talk about agentic AIs and in your day-to-day you are definitely far more technical in your role than I am. How is agentic AI presenting itself in your environment In a host of different ways.

Manny Silva: 4:55

So, as I already mentioned, there's Chad, gpt and Claude. Personally, I'm a Claude fan. I'm a Claude fan and so when I need to just talk something out to a rubber duck something, to use the engineering term then I can go to Claude to chat about it and it can perform research for me. It can validate assumptions, it can disprove assumptions, but it uses it with the built-in tools. So there's that most common of use cases. But I also use GitHub Copilot when I'm writing my code and even when I'm writing my docs, so that I can get suggestions directly in my editor. So I use VS Code even for writing my docs, my editor. So I use VS Code even for writing my docs. And GitHub Copilot is a wonderful agent for that interface because it can automatically suggest additional lines. If I'm making style edits, like changing things from title case to sentence case yes, I'm a sentence case guy then it can pick up that. Oh hey, manny changed these three headings to sentence case. Let me jump to the next one and try to. It suggests changing it to sentence case without him having to do anything. It picks up on those patterns and it automatically makes suggestions for me, or similarly, like reformatting a table or list items from using asterisk notation to hyphen notation and markdown, and it can just do all of that reformatting for me. But then, even more specifically, when I am trying to do larger revisions, I can switch to agent mode, which can analyze my code base and try to implement changes for me and run commands for me to validate the changes. That's all.

Manny Silva: 6:51

In Copilot I also have my AI tool suite, which is an agent. I recently rewrote it to be fully agentic so I can give it existing documentation fully agentic. So I can give it existing documentation PRDs, various design documents for new features that no AI knows of yet because nothing's been written about it yet and then pass it into my tooling to draft novel new content according to templates and best practices that I've established for use within Skyflow, and so that helps me with generating new content quickly and accurately. Of course, I'm going to heavily revise and review the outputs before we do anything with it, but all the same, the time to first draft is very short with it. But all of these different tasks I use agents for in different capacities.

Zohra: 7:46

Okay, so what I understood was you said I mean Claude, chad, gpt. These are agents because they'll go and fetch information. These are sort of the layer over the LLM, right To me. In simple terms, I would think that is the UI that's sitting on top of the LLM that allows me to interact with the LLM, is that?

Manny Silva: 8:06

right. Yes, generally, where the interface lives depends on the tool. Like Quad and ChatGPT, they're web interfaces, but Quad also now has a CLI tool so that you don't need the web interface. You can just use it on the command line. But it's still an interface layer over the LLM and that layer can take actions based on the LLM's responses, and so even that is an agent. It might have different capabilities than the web version, but it's a different interface which makes sense.

Zohra: 8:44

Got it. Thank you for that. And the second understanding or interpretation is the example that you gave with GitHub Copilot.

Manny Silva: 8:51

And GitHub Copilot specifically, is available baked into VS Code but also a whole bunch of other places. It can be in various other IDEs like JetBrains or Visual Studio. They'd have it available on the web in different capacities. They are baking Copilot into everything they possibly can, for better and worse. But all of these different interfaces have different capabilities. Some of them are fully agentic, like the VS Code integration. Some of them are pretty simple. But even the web-based interfaces that can look at your GitHub repos and answer questions about the repos technically those are agents, because they can go and they can fetch information about the repos. Some of them can create new issues, can create PRs, can create PRs, can create new releases, and so it's not just about fetching information, it's about taking any sort of action. That's what makes it agentic.

Zohra: 9:54

Got it. So again trying to revisit this definition, I'm trying to make sure that I understand this. There are so many different ways we can interpret what agentic AI means. In my world, at work, for example, I'm using Copilot and if I'm asking it some question that it'll prompt me. Would you like to create a user story? That action itself, that prompting that happens depending on what question I'm asking or what task I'm doing with the co-pilot. For example, I was trying to research something about a product and I'm using it in web mode and it prompts me to say, hey, it looks like this might be a good user story that you could track, and it found something in Azure and was able, so that in my world would also be agentic AI, right? Yes, perfect, now that I have dumped it so that I can understand. You mentioned that you use your own tooling to build your agents. Did I understand that correctly?

Manny Silva: 10:57

Yes, I built my own agents to perform tasks as I specifically want them to act.

Zohra: 11:06

Let's talk a little more about that.

Manny Silva: 11:08

So this is an evolution on some of the AI stuff that you and I have talked about before. A while back, we discussed how I built a system that could accelerate my time to first draft, and that was pretty darn awesome at the time, but it was essentially a glorified form that I had to fill out that with all of the necessary required information and then I hit go and I waited about 30 seconds to a minute and then it spat out a draft and I've improved upon it because that was not agentic. It was just given all of this input. What is my output Now? I can have a conversation with my AI just like any other chatbot, and then it maintains the entirety of the conversation history. I can give it my attachments so that it can be aware of the specifics of what I'm talking about without having been trained on the information, and then I can say, hey, by the way, give me a how-to guide for this subject matter now that we've discussed it, and then it will take not only the request itself but also all of the historical conversation. It can take all of the attachments and then it will identify oh hey, manny asked for a how to guide. I have a tool that can do that, that can draft a how to guide specifically, and it will go and say, okay, based on this drafting tool, I need a certain amount of information. I have the template for it and then, once I have enough information, I can go and do the draft. So let me go and fetch some more information. So it has web search built into it, so it can go out and it can search the web, it can ping our or it can search our knowledge resources for our current documentation, white papers, blog posts, all that and try to fetch more information from those. And then, once it has all of that information, it packages it all up and sends it off to the drafting tool. And so we're already talking about multiple different tool calls a web search, a knowledge graph search and then doing a draft action.

Manny Silva: 13:25

And the draft action takes all of this information and it'll say, all right, is the target audience apparent? No, let me analyze the request and all of the source documents to figure out what the target audience is. Cool, let's fill in that line. Is the target subject matter obvious or has it been specified? No, cool, let me figure that out based on the supplied context as well.

Manny Silva: 13:50

Okay, now that I have those, do I have a template specified that matches the request? Well, manny said a how-to guide. Yes, I have a how-to guide. Great, I'll use this predefined template. But if Manny asked for something like, I don't know, just a general summary or some other document type that didn't have a template provided, I gave it instructions for how to dynamically construct templates for various doc types according to Skyflow's best practices, so it can come up with a template on the fly that it can then turn around and use to draft new content, much like before, given all of the inputs, which are the equivalent of the form that I did before, but AI helped figure out all of the inputs and then it processes everything and generates that first draft and returns it back to me.

Zohra: 14:40

That is amazing. Now, how much time did you save by doing this? I'm sure you have saved a ton of time, even comparing ourselves to, probably a year ago, the way we were doing it the traditional or the ancient way and where you are today.

Manny Silva: 14:56

I mean I can give a very recent example. There was a in-depth technical tutorial that I was asked to create from some sample code. That was as a last minute request and in the olden days there's absolutely no way it was going to happen. It would just be like nope, sorry, that ship sailed.

Manny Silva: 15:23

In this case, I was able to turn around a fully fledged document within three days like deep, deep technical tutorial, like I wasn't able to do everything I wanted to do with it I mean, I'm only human even still but even that time, to first draft, I was able to take the entirety of the code sample repo, package it up in a format that an LLM would understand I'm talking the entirety of everything for the code repo and then supplement it with planning docs and an interview that I did with a PM who was making this request of me and I had a transcript of it. So the entire repo, the entire interview transcript, along with a guiding prompt of hey, I need you to create a tutorial that does XYZ and focuses on ABC with this lens, given this context, go and it did, and I had an initial draft in one minute and I was able to take that and fix it and iterate on it and restructure it, but I did in three days what would have easily taken me a full week before, if not more.

Zohra: 16:43

Was the content accurate?

Manny Silva: 16:45

Yeah, it even pulled in specific code blocks from the code that I gave it as context. It worked.

Zohra: 16:53

Okay, so we have to peel these layers, manny, because I need to understand, if you don't mind sharing, what expertise did you use? I mean, of course, your technical expertise, but how did you build this? But before we go there, I have this quick question which all of us are thinking about what does this mean for our profession?

Manny Silva: 17:12

Our profession does more than put words on paper. The only reason I was able to output things as quickly as I did was because I already had the interview with the PM, where I was asking all the questions I needed to ask with the intent of writing a document. I was able to sit down and walk through the entire end-to-end flow of what I knew needed to be covered in the tutorial. I was able to fetch that transcript and pair it with the code base, which normally wouldn't be available to an LLN in the full capacity that I was able to give it. I knew how to take each of those disparate artifacts and combine them in a meaningful way. I created the templates in the first place that humans use at Skyflow, but I made them available to the AI so that the AI could use them too.

Manny Silva: 18:10

This thing wouldn't exist without me and, to be perfectly frank, I don't think there are a whole heck of a lot of other people, even within the company, who would have been able to pull off the same trick, even with my tooling. It's not. Our specialty is in identifying requirements, gathering contexts, disregarding the things that aren't meaningful and then assembling what is left into our outputs, and AI is just a tool in the process. It is a hammer isn't going to build you a house. An AI isn't going to build you a dock set. It's the person using the AI who's going to build you the dock set.

Zohra: 18:53

And that's such an important distinction, because what you're telling me is you were in the driver's seat. There was human agency involved, otherwise this thing could have not moved forward 100%.

Manny Silva: 19:05

It never would have been called. No one ever would have. I had to be the one to sit there and actively choose to use it and actively take effort to make it as successful as it was.

Zohra: 19:16

Which is, I think, for me, takes away some of the intimidation that I feel, because the way the technology has evolved from the olden days to now, it's insane considering what it can do. And just with the example that you gave us, I'm wondering, you know, even though I feel reassured by what you said, wouldn't developers be able to do this? I mean, the role of technical writing is evolving very rapidly and those of us that are, you know it's a spectrum those of us with the skills such as yours are leaps and bounds ahead. But I'm thinking about myself very honestly. What does this mean for somebody like me who's not as technical? How do we kind of get to that point where we are constant One? We're not competing, but the reality is we are? When you start talking about the, you know when dollars are involved, that's bound to happen. But just considering where you are in your journey and where I am, I'm trying to see how do I overcome that learning gap?

Manny Silva: 20:15

So here's the thing I may have used my tool for this task, because it's my customized tool. Of course I'm going to use it. You could do something very similar with Copilot today, with Claude today, with ChachiBT today. It might not give you quite the same results that I got with my stuff because, again, it's not heavily customized, but you can say effectively so, first, if you have all of your necessary context you have interviewed your subject matter expert, you have your planning doc, you know what needs to be created. Great, you can go to Copilot today and say, hey, copilot, based on this interview transcript, based on this code reference, based on all of this context, all of this context, I need you to give me a tutorial that covers given subject matter and I want you to follow these best practices. Use the tutorial template by the Good Docs Project, which you can find at this URL. Apply the usage guidelines from the Good Docs Project's tutorial guide at this URL.

Manny Silva: 21:23

Go and make sure that you include bullet one, bullet two, bullet three. Do not include bullet one, bullet two, bullet three. Go. Or do you have any questions before you start? Answer any questions and then go, and it will give you something pretty similar. To be honest. It's just I baked in my own templates so I didn't have to reference external ones, and I have my own system prompts, so I didn't have to write it quite that extensively. But that's what it comes down to. If you give it adequate context, you can do it. Today. You are still going to have to very heavily edit it because different agents, different LLMs, are going to respond to requests to fetch external materials differently. They're going to process those materials differently. But you don't have to go out and write your own agent to make use of the agents that people have already built.

Zohra: 22:15

That's interesting. So, you know, let's talk about, I think, claude Chad. Gpt may be more familiar to our audience. I use Copilot in a work environment and it comes with a lot of limitations. I have just started experimenting with the agents at work, but chat GPT, I've built certain agents, for example, but this interview, when I go to my agent and I think I've called it some weird name, podcast question generator or something just to you know, make it really clear to me that I don't forget what this agent does I went and said this is Manny's LinkedIn profile and this is the subject that we're going to be talking about, and I need XYZ questions. And it was able to. Is that something akin to what you're doing?

Manny Silva: 22:59

Because, okay, Because, in this example, my LinkedIn profile is the context for the request of the interview transcript or the code repository. But you are giving a context to asking it a question. Is it going and fetching additional information as necessary? In this case, it's fetching my LinkedIn profile and it's using that information to satisfy the request. It took an action. It fetched information that makes it agentic. I have a very simple definition of what agentic is. If it takes any sort of action, great, but it's effectively the same thing. You didn't ask it, oh, and you did even ask it for to respond in a particular form. You asked for interview questions, and so that is effectively your template. If you wanted to get more prescriptive about what those questions look like, you could and guess what. That's just editing your template, or equivalent to editing your template, but it's, broadly speaking, the same task.

Zohra: 23:57

Okay, now you are making it super relatable to me. I feel like, okay, I can be in the driver's seat. Now you have done all this amazing tooling. You talk about the drafting tool, the knowledge graph, action, determining the target audience. It's fantastic. Are you using an API to do all this? Yes, okay, I wish I could spend a day with you, manny, just to see how you do these things.

Manny Silva: 24:25

Yes, I mean for context. Skyflow is an API first company. I live and breathe APIs and so calling an API to make LLM calls is another day for me. I understand it isn't for a lot of people, but I also acknowledge that I am a docs engineer. I do engineering tasks. A lot of folks don't. But yes, under the hood, all I'm doing is I'm saying, hey, given this context and this request, send an API request to Bedrock on amazon, on aws specifically and this model, and wait for a response and then parse the response and take action accordingly.

Manny Silva: 25:12

I'm using structured responses, meaning I tell bedrock you can only respond with one of these given values. So it's like, okay, you have to respond either true or false. Or, for example, you have to respond either true or false, or, for example, you have to respond with present, not present or whatever other keywords are approved, and that forces Bedrock to respond in a structured, predictable way. And then I just parse those responses. So whenever I need a response where I have to know what's coming in, I use a structured response. Whenever I want a freeform response, then I just let it respond as it will and I take that response as the input. But it's just an API call, and the real magic is not in the LLM itself, but how I knit the various LLM calls together.

Zohra: 26:05

I think that is so important, again bringing to surface the fact that you are the true agent here. You are the true director, actually not just the agent. You have the agency and you're directing how the AI tool should be used.

Manny Silva: 26:19

Maybe they shouldn't be called agents. Maybe they should be called actors. I like actor and director.

Zohra: 26:24

Exactly exactly, because an actor, actress as good as the director and honestly.

Manny Silva: 26:30

yes, there are other people who use the same, the very same agent that I built, and they use it in completely different ways than me and like, for example, I have it hooked into jira so it can look up JIRA issues and it can summarize JIRA issues and it can look, crawl related issues and answer all sorts of different questions. I don't use it for that. Others do and they're better at that than I am, even though I'm the one who built it.

Zohra: 26:57

And the more we use it, I feel, the more comfortable we become. At least, that's been my experience.

Manny Silva: 27:03

It's a tool like any other. The more you use a hammer, the more you get used to using a hammer and the better you get at using a hammer.

Zohra: 27:09

So you know, I always ask this question, manny, because just yesterday I was in a meeting where we were talking about what is technical writing going to be like in the next two years, in the next five years? Are we going to be around?

Manny Silva: 27:22

It's going to look a little different. It always is looking a little different than how it had previous. But I mean today I have already moved into what I call a content curator role, meaning I author content. Like the tutorial I just mentioned, I curate content from a variety of different sources, from various human contributors throughout the company. As of right now, I am working to enable a self-healing system such that when I'm able to detect an issue with a Docs as Tests tool, like Doc Detective, programmatically meaning, for those of you at home who are not as familiar with it I have a set of tooling that automatically runs all of the procedures in my documentation every day and if any of those procedures fail to perform as written, then we have identified an issue. And if we've identified an issue, I'm working to pass it into a self-healing system so that it can analyze the issue and try to identify where did this issue happen. Is this an issue in the docs? Is this an issue in the product? Identify where did this issue happen. Is this an issue in the docs? Is this an issue in the product? And if it's an issue in the docs, then try to fix it, figure out what the correct content should be and create a change request so that me, hugh and Manny can review it in the morning. If it is an engineering issue, try to raise issue in the proper engineering channel to notify people that there's something worth investigating, and there are a variety of companies trying to do that whole task in different ways.

Manny Silva: 29:12

The whole self-healing gox agent is a thing that I think we're going to have to get more comfortable with in the near future, but that's what we're moving towards.

Manny Silva: 29:22

That's what I'm actively moving towards, and so, while I may not be sitting down and putting as many words to paper as I use or digital paper as I used to, then I'm still a tech writer, I'm still a docs engineer, I'm still curating our content and making sure that anything and everything that gets added follows our content styles and standards, that it fits into the information architecture, that it doesn't upend our content strategy, that we're not duplicating content that we've already created elsewhere, because all of these people, whether they're AI, whether they're human, aren't as intimately familiar with why we do things in the docs as we do them.

Manny Silva: 30:10

That's what we're still here for. We still have to uphold our standards, apply our standards and make sure that everything has a unified voice to look at the analytics from our docs and figure out what needs work, figure out what needs more content. All of that we still have to do. We don't just write words. We do so much more than write words, and if there's a tool that lets us write more words, cool, that sounds good to me, but it doesn't take away from the rest of our job.

Zohra: 30:42

Yeah, I think the very fundamental question that I'm asking myself at this point is what skills have I given up? I haven't. I'm literally going back to the very foundational skills that I came into this profession with, and I'm probably depending on them even more at this point from everything that you're sharing and as it resonates with me, right.

Manny Silva: 31:03

Yeah, our skills haven't changed. You still need to write well, because to edit you have to be able to write well and you're going to have to edit, probably more than you did before, but the underlying skills haven't changed. Your ability to interview sneeze hasn't changed. The underlying skills haven't changed. Your ability to interview sneeze hasn't changed. Your ability to know what fits and what doesn't according to your company's guidelines hasn't changed. It's just there's a new tool on the block that can fetch information for you and, if you want it, to draft information for you and I understand that that's intimidating to a lot of folks and, frankly, for good reason but it's a tool and it's just a tool. If you learn to make use of it, if you take the time to get comfortable with it and really explore its boundaries and see how you can make it applicable to you, then it will empower you tremendously.

Manny Silva: 32:03

One of the issues that I see a lot of tech writers facing with the current suite of tools that are available is that they're all generalist tools. There are a few coding specific tools that are targeted for engineers, but otherwise it's just cool. I'm ChatGPT, I'm Claude, I can do anything, but there's nothing that's specific to tech writers, so rarely is there anything specific to tech writers or technical communicators more generally. Unfortunately, right now the onus is on us to figure out how to most appropriately apply the current tools to our tasks, and that's where we have to push the boundaries of what we feel comfortable doing to figure out how we can best make use of these tools.

Zohra: 32:51

I think that's great advice there, Kind of a philosophical question, you know. It seems like we had to, over the last few years, learn how to interact with AI and now, if you just look at the whole journey, it has been one of tremendous growth in my personal opinion. That's how I would like to look at it, Because something was given to me. Did it make my job easier To some extent? Yes, it did. Did it add challenges? Absolutely it did, Because now I had to take out the time to go learn this tool. So I would look at that as a challenge.

Zohra: 33:24

But today I can do a lot more, I would say efficiently, productively, of course, not ignoring the fact that you still have to keep in mind that it can still hallucinate. We're talking about generative AI, just so my audience is clear the generative AI hallucinate. We're talking about gendered AI, just so my audience is clear the gendered AI, the LLMs, can hallucinate. You always have to verify your data, all of that. But when I look at how I'm spending my day, my typical day to day, I feel like I'm able to do a lot more context switching, and I'll come to my question why I'm kind of going down this rabbit hole, trying to take you through my day, so please bear with me. The amount of stuff that we are doing now is far more. Like you said, you were able to create a tutorial within three days. You had the output, the draft, in a minute, right, yeah, what does this mean for our brains in terms of the burnout? That was my philosophical question.

Manny Silva: 34:20

Yeah, it is real. I mean, we burned ourselves out before. We had all of this ability to context switch as quickly as we can now, but we have the ability to burn ourselves out that much faster nowadays and we have to be careful with our time. We have to be careful with what work tasks we accept on what timelines. Something I learned the hard way, before generative AI was a thing, was that people are going to have lots of ideas about what can be written in the docs, how we can go about doing things, what tasks need to be performed, and they're going to send you lots of ideas on a regular basis and if you accept them by default, you're in for a bad time because you're going to be overworked, you're going to be underappreciated and people are just going to keep tossing stuff over the wall at you to complete, and that is a recipe for disaster, that's a recipe for feeling underappreciated, that's a recipe for being overworked, that's a recipe for burnout. And you can't do that, ai tooling or not. Ai tooling makes it harder because people assume uninformed people assume that you can magically whip up a document. That needs care and consideration. Even if you can create the first draft quickly, it still needs care and consideration, and that you can do it in oh you know an afternoon, when, in reality, it's going to take you three days, even with AI assistance. And if other stuff comes up between the requests and the response, then well, if you decide to take that on, you are doing yourself a disservice because you're so heads down focused on a given task. If you constantly switch between one task to another, to another, to another, you are going to exhaust yourself, and so it is more important than ever that we protect ourselves, that we make sure we are not overburdening ourselves, because we still have to put in effort. Sure, these tools can give us back text, but everyone listening to this knows that text does not, in itself, necessarily make good content. We have to curate the text, we have to edit the text, we have to do all of the things we ever do, regardless where the text came from, and so if you keep taking on new tasks, you're going to burn out.

Manny Silva: 37:00

One of the things that I've had to do, and I've done for a long time, is when someone comes to me with a request, I say that is a good idea. Certainly it legitimately is. Why don't you give me a draft. Why don't you write up an outline? Why don't you summarize this for me or put your thoughts together in a doc for me and share the doc with me?

Manny Silva: 37:25

Give them some amount of friction, even if it is a legitimately good idea. Have them help you because it is their idea. They are invested, they want it done. Capitalize on that. Get yourself something to work off of. Don't force the interview right then and there. Don't set yourself up to have to do an interview in the future. Have them give you something that is at least semi-coherent, and then you have something to work off of and they're happy that they were able to contribute. Sure, it might sit on your backlog for three weeks until you actually have the time to prioritize it, but all the same it makes them feel heard, it gets you an actionable artifact and it doesn't immediately get thrown on your plate because they realize oh hey, actually this is a lot of effort and maybe Manny or Zora has got something going on right now and they can't tackle this immediately, because it just took me an hour and a half to put together some rough notes, so how could I expect them to whip it together in an afternoon?

Zohra: 38:18

That's great advice. I think I liked the way you phrased it. Give them some friction, because then it helps, hopefully, make them pause and think about okay, this is going to take us longer than anticipated, and everything else that you said, manny, I think it's true. We are having boundaries, learning to time box the things that we've always been doing. So we are, of course, we've been burning out and we are burning out even more, but what do we do to maintain our sanity? Those skills, we have those skills, I guess, available to us in our toolbox, and we don't have to grow a new muscle there. We already have it. We just have to utilize it even more so.

Manny Silva: 39:02

Yes, and I mean I know in my experience generally with technical communicators and I know how I feel personally a lot of technical communicators tend to not necessarily be people pleasers. But we like to help. That's why we're in this role, and so when someone comes to us asking for assistance, many folks have the initial reaction of yes, great, I can help this person out. How can I assist? That is not a bad thing. Our empathy is what makes us as effective as we are. But unchecked empathy is a recipe for disaster.

Manny Silva: 39:46

So we have to establish these healthy working boundaries, because if we don't, then we're just going to get flooded with more work than we can handle. And even if we have healthy working boundaries, we may still feel like we have more work than we can handle, but at least we can prioritize it and people aren't getting emotional about it. If we tell people how we operate, then they just know oh hey, this is how zora operates, this is how manny operates, this is the docs team's service level agreement, so that this is just how they process requests. It's nothing personal, it's just the process, and that helps tremendously in setting expectations for external requests and in helping the docs team protect themselves from way too much coming in all at once.

Zohra: 40:32

Yeah, I'm just so glad that we talked about this, because I'm just thinking about companies where these boundaries aren't clear, where there's a lack of process that you talked about.

Manny Silva: 40:40

Then you're not setting expectations and in those situations, especially with AI becoming such an integral part of our day to day, for many of us we may just be at the start of this journey, especially for those people who are early on, is you need to bulk up your internal documentation, you need to write down your processes, you need to formalize your processes, you need to socialize your processes Because when you have a written down procedure for how you do request intake and response, if you inform everyone what might feel like a little aggressively, but if you make sure that everyone is really, really informed about how you do docs, requests, then when someone comes in and tries to barrage you with too much stuff, you can just point to the request and say, nope, this is how we do it and, hey look, problem solved.

Manny Silva: 41:46

And if problem isn't solved, then you can escalate to whoever you need to and say this is the process that we have socialized and is formalized, was approved by this person, that person and the other person and this person isn't following it. So I'm not saying that we need to put together processes for everything no, that's ridiculous and leads to bureaucracy but putting formalizing processes so an engineer who wants to help but doesn't know how to can reach out and they have expectations for how you're going to respond to them to fix a problem. Or a PM who has a new feature coming in and wants to have docs but doesn't know where to start Now, has something to latch onto and has an idea about turnaround times. This helps everybody. But in organizations where internal documentation is severely lacking, where internal documentation is severely lacking, there's a lack of focus. There's a whole lot of thrashing as people try to get stuff done because they don't know how to get stuff done internally, because it's not written down.

Zohra: 42:51

Right, and I've been in situations before where I was. I have faced the brunt of this with lack of process, as you said. Lack of process it doesn't matter whether you have AI or not. Lack of process is going to create that unwanted stress At a place where there is good process and again that process evolves and you have to pivot. But the point is you have to start with a process. Without a process it's going to be chaos. So I think your words are absolutely true. If you are at a startup, start considering, start looking at what those processes might be. It doesn't have to be bureaucratic, but setting clear expectations is absolutely important, especially as we kind of move into uncharted territory, as we go further into this whole Gen AI thingy.

Manny Silva: 43:43

And for people who need some backing or resources to point to when it comes to building out internal documentation. Look up the DORA reports by Google that's DORAdev, d-o-r-adev, d-e-v and they have analyzed the impact of technical documentation on organizational success and the findings are pretty dramatic. The 2023 report, if memory serves, shared that organizations with a robust culture of internal documentation end up like 175% more successful than those that only have moderate. So not even lacking, but just moderate versus robust is 175% improvement. Wow, and there are multiple talks that have been given about this at Write the Docs, I believe last year at the Winix Foundation Open Source Summit, and those are available on YouTube. So please arm yourself with statistics. The DORA reports are focused on engineering efforts, but they really highlight the impact of internal documentation and just how important it is for everyone in the organization.

Zohra: 45:07

Excellent, excellent. See, this is why I do these interviews, manny, because I learn so much. Thank you for bringing that. I'm personally intrigued and I'm going to go take a look at this, because I have been in situations where there are the lack of process has completely burnt out the documentation team and again, we are under appreciated and we are people pleasers to some extent and we don't learn to say no. So having these boundaries, good processes and good internal documentation is definitely going to be helpful.

Zohra: 45:38

I know we have barely seven minutes left, but I wanted to ask you, manny, as we start using more of these agentic experiences in our day to day, I suppose good documentation itself, content, is extremely important, because if you want your tools to go fetch information for you, that information to begin with has to be reliable. So it's your opinion, if you had to give a checklist of maybe three or four or how many ever, maybe we should say five if you have five, if you have three, that's great. What would that be? Oh, like'm sorry I put you in the hot seat here.

Manny Silva: 46:16

No, no, that's okay. Like what would my checklist be to make sure that the documentation is ready for agentic use?

Zohra: 46:25

Exactly yes, thank you.

Manny Silva: 46:28

Cool, make sure it's up to date. There is nothing worse from an engineer's perspective and engineers are going to be the first ones making heavy use of agents. There is nothing worse from an engineer's perspective than having an AI suggest that you use an outdated version of a tool. And so if your docs aren't fully up to date, then guess what's happening to the engineer trying to use your tool to date. Then guess what's happening to the engineer trying to use your tool. If your docs are inaccurate, which I think is slightly different than up to date, then that gives an even worse response to the engineer, because then the AI tool is acting on all the information it has available to it and it thinks it's accurate, but the engineer is having to debug a whole bunch of stuff that the AI can't help it with can help them with. So keep your docs up to date, keep your docs accurate. Have your docs accessible. Note that I and what I mean by accessible is get it in a place or format that an llm or agent, a tool, can ingest it, whether that's something like using an LLMstxt file, whether that is an MCP server, if that floats your boat, whether it is whatever format, if even if it's just making your docs publicly available, like a source content, itself publicly available in a GitHub repo. Cool. Just make it available so that an agent doesn't necessarily have to go to your docs. As a human sees it, this helps you prioritize the agentic experience, or AX, rather than user experience or UX. Let's see, we're at three so far. Keep your docs up to date, keep your docs accurate, keep your docs accessible.

Manny Silva: 48:14

Then I'm going to go a negative on this one Do not update your docs for agents. Specifically, what I mean by this is don't change how you're writing to cater to agents. Agents should be able to ingest everything that you've written as you've written it for humans, because guess what? That's what they were trained on in the first place. They can interpret Markdown tables just fine. They can interpret whether you've got DITA formatting, whether you've got restructured text, ascii doc Markdown. There is no best. It can ingest all of it, and so don't change how you write to cater to agents.

Manny Silva: 48:55

But and this is going to be my fifth and final one be consistent in how you write, because that's not only going to benefit agents, that's going to benefit humans, that's going to benefit everyone. Be consistent in your terminology, be consistent in your phrasing. Be consistent in how you title various different headings phrasing. Be consistent in how you title various different headings. Consistency will make it much easier for LLM to infer against, to make it easier for your human readers to navigate and find your content and understand your content. Oh, also, be consistent in your structure of your various different docs based on doc type. And you know what I'm going to go to a sixth one as well.

Manny Silva: 49:38

Make sure you call out explicitly the things that you have implied. What I mean by this is we write very implicitly If we don't say product A works with product B, then we imply that product A does not work with product B because we didn't say that it did. But LLMs don't get that. They just see two things in isolation and if they look kind of similar, then an LLM may well hallucinate oh hey, we might be able to knit product A and product B together.

Manny Silva: 50:09

It's not the case, and there might be some humans who are sitting there reading it being like well, it looks like product a and product b might knit together. Let me bash my head against the wall for a few hours to see if it can work. And of course it doesn't. And so one thing that we can do to benefit all of our users is be more clear and upfront when it comes to when things do not interoperate, because then lm has the outright negative. It needs to be able do not interoperate, because then the llm has the outright negative. It needs to be able to say no, these don't work together and humans don't have to make assumptions based on implication got it yes so there you go.

Manny Silva: 50:46

Those are six things fantastic tips.

Zohra: 50:49

They're fantastic and you know, as you were talking about being consistent, I think that should be par for the course for us being clarity and consistency should be there regardless. But it becomes even more critical because, without the right context, your agentic experience is going to be not so great. And, like you said, you know we don't want to be banging our heads against the wall. We want good. Ax only comes when you have good content and and that I mean I guess that leads to good UX.

Manny Silva: 51:19

Yeah, I mean good docs. Underpin all of this is the short version, so we have to make sure our docs are better than ever.

Zohra: 51:27

Right. So, I mean, the responsibility is still on us as technical writers. We may be curating content, but we also have to do content audit for all the things that we talked about that, Manny, you shared with us for the sake of consistency, accuracy and just a better UX overall.

Manny Silva: 51:47

Yes, and here's the thing, it's completely within our ability. We may spend less time writing. Well, guess what? There are other things that could use our attention, that we haven't been able to give the attention that they've really deserved. So now perhaps we'll be able to.

Zohra: 52:03

I think that's a great point and I would love to end on that note because the things that we couldn't do, we can. Now we have that possibility with these tools available to us, and content audit has been one of my biggest challenges to make sure that the content remains accurate, and in my current role I'm not maintaining different versions, but for those of us that are, maybe this is your opportunity to go do that content audit and maintaining your content so that its shelf life is, I guess, maintained and relevant to the user, agreed full way we were relevant to the user, agreed fully. We were going to talk about audio synthesis, manny, I think I might want to call you back on that.

Manny Silva: 52:41

Sure.

Zohra: 52:42

We should talk about that, because we were going to talk about agentic AIs and audio synthesis within agentic AIs. Is that right?

Manny Silva: 52:50

Yes, audio synthesis, multimodal AI Generally. There are a whole lot of ways that we could make use of it, even today in our docs.

Zohra: 53:00

And I want us to have a good, wholesome discussion on this. I don't want to rush you myself or my audience, because these are things that we need to start diving into. We are past this whole thing about AI literacy. I think now we are like we are all in. We learn to swim or sink. Let's learn how to swim together.

Manny Silva: 53:18

Happy to be the swimming instructor.

Zohra: 53:20

Thank you, I love that. Thank you so much, manny, for being on my show. This has been a fantastic start to my day and I hope you had fun with me.

Manny Silva: 53:28

Oh, always, zora, Always, thank you for having me.

Zohra: 53:31

Listen to Inside Techcom on your favorite app and follow me on LinkedIn or visit me at wwwinsidetechcomshow. Catch you soon on another episode. Thank you for listening. Bye-bye.