Why Docs Toolchains Should Match Contributor Needs? With Laura Novich, Salesforce

Transcript:

• 01:13 – 03:40 –Laura’s Journey into Technical Writing

  Gowri Ramkumar:Good day, everyone. Welcome to Knowledge Base Ninjas podcast. With us today we have Laura Novich, Lead Technical Writer at Salesforce.

  Hi, Laura. How are you doing today?

  Laura Novich: Hi. I’m good. Thank you for the opportunity.

  Gowri Ramkumar: The pleasure is ours, Laura. Now, I’m very eager to know a lot more about you, so please feel free to explain how did you get into this professional journey and who was your inspiration and how are you enjoying so far?

  Laura Novich: I’ve been a technical writer for quite a few years. I started back in 1997, so I’ve, been with many different companies over the course of my career and influences, I’ll go into, I guess, later, there’s quite a few. But, one of the reasons why I entered into technical communication was I’ve feel and still feel this way that, instruction is a part of my soul.

  So I started, as a teacher, teaching English as a second language to adults and to children in colleges and in even elementary schools and nursery school. And eventually I got to the point where, this wasn’t going to be a lucrative career for me. And in order to support my family, I needed to look elsewhere. Friends of mine were already technical writers, and they said to me, you know, Laura, this is what you should be looking at. You are natural. This would be great for someone who loves to educate. And, they were right.

  So after careful consideration, I enrolled in a quick course, and a few months later, I found my first job, and, honestly, never looked back. And it’s been, you know, a very amazing career for me. So amazing that I even recruited both my husband and my daughter to join me in the effort. And now they are both technical writers as well.

  Gowri Ramkumar: Oh, wow. So, just out of curiosity, what kind of conversations do you have around the dinner table then?

  Laura Novich: Honestly, sometimes we’re arguing over the Oxford comma. Sometimes we’re arguing over the use of hyphens. But ultimately, we’re arguing over, good user instruction and design.

  Gowri Ramkumar: Alright. Very interesting, Laura. Now, I’m sure you’ve got, as you mentioned this, your experience is immense.

• 03:40 – 05:10 –Building an Effective Documentation Toolchain

  Gowri Ramkumar: And now, in your experience, what are the most critical components of an effective documentation toolchain?

  Laura Novich: So in my experience, the most critical component of effective documentation toolchain would include compatibility and integration. And this is especially true with technical communication where authoring tools, graphics, tools, publishing systems don’t always work seamlessly together. Sometimes it’s less like assembling Lego pieces, and more like forcing pieces from different puzzle boxes to fit in together. Trying to make things that don’t naturally belong with each other to belong.

  And, but beyond the technical interoperability of tools, what’s even more important is how effectively people use them. A well integrated tool chain is only good as a team behind it. So, ensuring the writers are using the tools properly, efficiently and to their fullest potential is the key.

  And this includes taking advantage of, you know, features such as, you know, content reuse or structured authoring, automation and collaboration. And when all of these things are integrated and this process is streamline and friction is reduced, work just becomes easier and more productive. And that makes everyone more motivated as well.

  Gowri Ramkumar: Absolutely, very well said Laura. The tools are just only there to assist you and not to reduce your work. Right?

• 05:10 – 06:43 -Choosing the Right Tools for Your Contributors

  Gowri Ramkumar: So now how do you determine that the right tools are working for your documentation process? Particularly, I’m sure you’ve got a mixture of technical as well as a non-technical contributors in the organization. So how do you know that the tools are working?

  Laura Novich: So not every toolchain will fit every organization. So my experience may not apply to all of our listeners out there. But one thing you do need to consider is this, when selecting your tools, you need to decide who is actually writing and contributing to the documentation.

  Sometimes it’s not just technical writers. It could include developers, product managers, support teams, and sometimes even marketing. Yep. And once you understand who your contributors are, the tools that you’re using, and their level of expertise, the next step is to find their comfort level with those different tools.

  Developers might prefer something lightweight and code adjacent, like, Markdown in VS code, or adding comments to an existing API in order to auto generate documentation. Product teams may be more comfortable documenting Confluence. Marketing teams WordPress, Support teams, maybe in Salesforce. The key is to meet people where they are, especially if they are frequent contributors.

  Asking a non-writer to work in a structured authoring tool, the steep learning curve will create resistance and slow everything down.

  Gowri Ramkumar: Very, very nicely put.

• 6:43 – 07:36 –Creating a Flexible Contribution Ecosystem

  Gowri Ramkumar:Again, in relation to the same question, how do you make this whole environment work flexibly, both non-technical and the technical contributors?

  Laura Novich: So to make it work flexibly, you have to have a system in place that allows for contributors to contribute content with the tools that they are comfortable with. And the magic of it all is making it all appear on your documentation portal. So if you have a omnichannel portal where you are able to pull from different sources and have it all be represented as one piece, as if one author wrote it, that’s where the magic is. And making that happen requires you to have carefully guided templates and carefully guided structures so that each contributor understands what they’re meant to do and how they’re meant to do it.

  Gowri Ramkumar: Great.

• 07:36 – 09:25 –Bridging the Gap for Non-Technical Contributors

  Gowri Ramkumar:So are there any particular training that you do or do you have in mind? Well, when it comes to you know, engaging the non-technical writers in this process?

  Laura Novich: So with a non-technical person or non-technical writer, often what, inhibits them is finding information at a level of their understanding. Right? So there are plenty of sources out there that will help people, understand technology at a level of that they’re ready to understand it at.

  And there are communities such as, Write The Docs where people can actively find out that information. There are thousands of users there. And each channel within. Right? The docs slack allows you to pinpoint the area that you are most interested in learning about.

  And from a simple question, you will be able to get thousands of answers from very supportive community. In addition, now with the availability of AI, information is more accessible than ever before. You can research everything and anything from, brain surgery down to nanotechnology and with the benefit of AI as your copilot, it makes you a much more stronger person in terms of your knowledge.

  And then what happens is, when you meet a subject matter expert, you are more prepared and that preparation will allow you to feel more confident. And once you are more confident, then you will take more steps to increase your knowledge level. And you will no longer be that non-technical technical writer anymore.

  Gowri Ramkumar: True.

• 09:25 –10:02– Measuring Success in Documentation Training

  Gowri Ramkumar: Any metrics that you measure, particularly while doing these training programs?

  Laura Novich: So one of the biggest metrics I use in training is, how well does a trainee take a skill that is learned and adapt it to something else? I don’t want to see a trainee who only works of things that are spoon fed to them. I want to see them develop. I want to see them grow. And I want to see them apply the skills that they have learned, to something that is new.

  Gowri Ramkumar: Yeah. Okay. Got it.

• 10:02 – 12:20– ⚡Rapid Fire Round

  Gowri Ramkumar: Now moving on to the rapid-fire round questions,

  Laura, the first one is I’m sure you read a lot of resources, particularly on the documentation site.

  Anything in specific that you would like to highlight for audiences today?

  Laura Novich: Sure. So there’s a few places I go to for information. Let me spell them out for you.

  So one of them is again, Write The Docs slack. Another site that I use frequently is the Content Wrangler. They have a lot of webinars there. And you can learn about all types of industry trends. And I go to that site pretty often. Okay.

  In terms of blogs, I follow Tom Johnson’s blog, I’d Rather Be Writing. As well as, Fabrizio Ferri Benedetti’s passo.uno, both of these blogs are amazing in terms of their content. And in terms of how much content that is there, there’s just a ton of information there to help you learn all about all different aspects of technical documentation.

  Gowri Ramkumar: Fantastic. Thank you so much for those resources, Laura.

  Now, one word that comes to your mind when I say “Documentation?”

  Laura Novich: This word, I don’t know if anyone has used it, but if they have, I’d love to meet them.

  The word is value.

  Okay. So, when I think of value in documentation, I picture how product documentation directly enhances a user experience. And this for me was the unbelievable moment that allowed me to understand that this is the career I was meant to have. Okay. When I see users reads documentation or follow documentation and connect with a product, that’s all I need.

  Gowri Ramkumar: Fantastic. Yeah, that sense of achievement or making somebody understand from your own words is unimaginable. I can see. Right.

  Now a piece of advice to your 20 year old self?

  Laura Novich: So, piece of advice for my 20 year old self a long way ago, but, I’m actually telling myself, don’t try to learn it all at once. Focus on mastering one little thing at a time, by making small steps and marginal gains. And that’s how you make progress.

  Gowri Ramkumar: Okay. Nice one. Laura.

• 12:20 – 16:58– Real-World Scenarios

  Gowri Ramkumar: Now, I know I try to ask as much as possible with the given time, but then, please, Laura, feel free to add anything more that you would like to highlight today.

  Laura Novich: Sure I can highlight a few things if you want to go back to, I can give some examples of different things if you like, if that makes sense to you.

  Gowri Ramkumar: Sure. Yeah.

  Laura Novich: Okay, so, you mentioned about tool chains. And I can cite a couple examples of how this actually worked in the results that I actually saw.

  So in one case, I was hired as a sole technical writer for a company that had a bunch of developers.

  It was a startup. They were scrappy and they had a solution already in place for their documentation. It was a doc source code, toolchain. And when I was hired, I was told, Laura, if you can get the developers to write the documentation and join you in the effort, you will have mastered a lot. So I said, okay, I’m going to roll up my sleeves and dive right in to a company whose technology? I didn’t even understand at the first. So I relied on the developers to give me at the very least, a first draft of what the documentation was supposed to be and look like. Having the docs stay in the current existing toolchain and having me learn those tools was actually the best idea, because it kept the 25 contributors happy because they were already in their happy place. And it meant that I was orchestrating, the documentation and keeping everything going and improving it over time. So that’s exactly what happened.

  And not only did, the 25 technical writers stay writing documentation, I recruited some more as well. So, and what was interesting is that documentation changed the idea of it, the notion of it, it changed from a necessary evil to a capital driving, revenue driving component. And that change where everyone’s is suddenly focused on documentation, where there’s no way we are going to sell a product without documentation, where it’s not, where the definition of done means it’s documented that change would never had happened if I had introduced, toolchain that the developers couldn’t use. So because I met them as an equal partner and told them I was going to advocate for them to have things be the way that they were comfortable doing it meant that, they were more enthusiastic about the whole process.

  Gowri Ramkumar:Makes sense. Wow. Thank you for sharing this experience.

  It really, I can’t see how it works, but then we can clearly see how if everybody works together, great things can be achieved. Yeah.

  Laura Novich: And on the other end of the spectrum, I had another situation where my audience for contributors, were product managers. They were the experts of the product, and they were they told me that, they spent countless hours, creating videos for customers holding their hands, explaining things to them because the documentation just wasn’t effective. It wasn’t adequate. So I said, okay. What tools to you enjoy writing with? And they told me, without any hesitation at all, Confluence. I said, okay, fine, we’ll use Confluence. And the next thing I know, we created a knowledge base out of Confluence.

  We escalated, from 300 articles to 2000 articles within a year. And all the product managers were contributing to the documentation effort. We also hired additional writer along the way, and together we created this ecosystem where, documentation shined. And then once we got that knowledge base working, we said, okay, let’s redesign our doc portal. Yeah. And we did. And we made it something that, everyone was proud of. So that when customers were, being prospected and, sales were talking to them, those discussions revolved around our doc portal.

  And again, what happened was, is that now the focus changes and all of a sudden documentation becomes something of value. And, for me, you know, personally becomes a source of pride.

  Gowri Ramkumar: Very true. Well, that’s so amazing two experiences Laura. And thank you so much for sharing this. And I’m so glad I asked you that last question.

• 09:25 –10:02– Final Thoughts

  Gowri Ramkumar: Now, thank you so much again for your time. And, all the very best for your future projects. And I’m sure you’re going to do much more wonders in the coming years.

  Laura Novich: So thank you. Looking forward to it.

  Gowri Ramkumar: Thank you. Take care.