Content Frameworks and Their Impact on Docs with Betty Mann, Oracle

Transcript:

• • 01:08 – 04:40 Betty’s Journey into Technical Writing

    Gowri Ramkumar: Good day, everyone. Welcome to the Knowledge Base Ninjas podcast.

    And with me, I’ve got Betty Mann, Principal Technical Writer at Oracle. Hi, Betty. How are you doing today?

    Betty Mann: Doing very well. Very excited about being on this podcast. I’ve been listening to it and stuff. So thank you so much for having me.

    Gowri Ramkumar: Fantastic.

    So we are also excited to hear a lot about you. But before we dig deep dive into any further technical things, let me just get understand, how did you land up in technical writing and how is it going for you so far?

    Betty Mann: Amazing. So. Yeah.

    I guess I’ll start at the beginning. So I did a computer science degree. I didn’t really know what I wanted to do. I think out of school and uni, still, I was a bit like so many options and so many opportunities. I don’t know what I want to do. So I, but one of my major points, I guess, was when I joined a startup and they gave me a lot of ownership. The startup it’s Chattermill, and they leverage customer feedback and then use AI to sort of uncover insights. So it was there where I sort of found out that I wanted to be a customer advocate and promote the customer experience. So there I ended up making, like, building a support team, which then again linked my love of communication with problem-solving and all the different areas of technology. I still found that I was touching of everything, which is exactly what I wanted.

    And then when I moved to a larger company, they actually suggested that I go on the flip side of the coin. So instead of for, you know, instead of post, so after if someone has an issue and comes to support, what I get the docs and like preempt it and think about the customer in that way, and hopefully fill in gaps before they even get to them. So yeah, it wasn’t a route that I had initially thought of at all. But I really love it.

    You asked how it’s going. Yeah. I love talking daily with sort of the experts in their fields and, putting myself in the user shoes to try and make the docs as clear, as concise as they can be. It was quite hard at first, like not being the smartest in the room sometimes.

    Gowri Ramkumar: Yeah.

    Betty Mann: The bigger….

    Gowri Ramkumar: You learn, you learn.

    Betty Mann: Exactly, exactly.

    It was a big learning curve, but I found out, actually asking stupid questions. You know, the customers will probably ask similar things as well, if it’s not clear. So it’s quite good. I, what’s it called? It just suits my way of thinking. I have a brain where I’ve got a lot of tabs open generally. So, like having an SME and then also maybe an internal doc and a GitHub repo, and, like, merging them all into one specific page with everything you need. It sort of works for me.

    Gowri Ramkumar: Fantastic. Yeah.

    I don’t know if you, if you listen to some of my podcasts, already a lot of them talk about,

    when you start your career, you’ve got to be very open, ask questions, don’t hesitate to ask. And I just remembered those advice. And then when you said that I used to ask a lot of questions. So. Yeah, you’ve done the right thing. Yeah.

    Betty Mann: Exactly. Exactly. It’s about ego. I guess. Not having an ego, which.

    Gowri Ramkumar: Yeah. Yeah.

    Betty Mann: It was hard to start with. I was like, I should know this, shouldn’t I know this? But sometimes, you know, I’m not the expert. I’m the one who’s making it user-facing, so yeah.

    Gowri Ramkumar: Nice. Fantastic.

  • 04:40 – 06:25 Why Defining Content Types Matters for Documentation Teams

    Gowri Ramkumar: Now, I think you would be the best person to answer this question for me as well.

    Now, why is it important for the documentation team to define different page content types instead of treating all contents?

    The same like you mentioned, based on the audience and also the company size, you had to learn a lot and unlearn a lot of things, right? So why is it so important?

    Betty Mann: So I think, yeah, if you treat everything the same, it becomes super hard to sort of navigate, like I liken it to like, you know, you’ve got that draw which has like, plugs and batteries and manuals and it’s just sort of like a miscellaneous draw. And it’s probably got exactly what you need for this situation, but you can’t find it. You don’t know where you’re looking. It’s just a mess in a way. So defining content types will help a user find and then work through what they’ve come for, like what the purpose is. It makes it very clear for them. And I feel like even in a team, so not just for the user, but even in your team, like the docs team or the product team, it creates a lot of efficiency. So it makes your docs easier to maintain at scale.

    You can avoid duplication if you’ve got, like, certain pages dedicated to certain things. You can have it like if you’re asking me to review your document, they could do it faster. They know exactly what the document’s purpose is. Also, I guess having a framework sort of lets you focus on the actual content each time. So instead of, wondering how you’re going to word it or put it or like, if you’ve got some sort of template. Yeah. You can actually focus on the content more.

    Gowri Ramkumar: Great. So I think you kind of partially answered my next question as well.

  • 06:25 – 08:22 Standardizing Docs with Content Types

    Gowri Ramkumar: How do you go about standardizing your page content types in the documents?

    Betty Mann: Nice. Yeah.

    So I think when I started doing this, I sort of looked at the sort of users who would use it. What’s a user journey they would go through? I guess someone like a solution architect would just want to see maybe the key features or like the benefits, or maybe even a quick get started guide to know what’s possible. Whereas an engineer who’s actually coding it might go deeper into the documentation. So yeah, I tried to think of all the different questions that user would have at all the different stages, and sort of map them to the different content types.

    I ended up using, and the DITA, which has, I think, four main, I mean, if I’m wrong, but this is well, I live by now, so hopefully. So yeah, you sort of got the question. I want to know what this does, and that would be an overview. I want to understand what it does, which is like or how it does what it does concept. I want to do it would be a how-to guide. I want to do it quickly. And with the happy path, I get started and then like I want, the building blocks would be more of an API reference. Yeah.

    I had initially I had tried one of the jobs I had previously where I was implementing this, the docs, I wasn’t public yet, so it was hard to sort of iterate on that and know that this was the correct way of doing it. But I ended up linking in, and product engineers just asking as many people as possible to get feedback on it. And they are the sort of users who would be using these sorts of pages. So even within your team, having that sort of feedback like it is quite important. We also used hackathons and gave teams of use cases to go through the docs and make something or integrate with something, to watch how they interact, because I guess, depending on your experience, will you start at the get started or you go straight into the API reference because, you know, the general gist of it?

    Gowri Ramkumar: Yeah. Understand. Great.

  • 08:22 – 10:29 Style Guides and Templates as Blueprints for Docs

    Gowri Ramkumar: Now, you mentioned about using templates or style guides with the teams to make sure, the different types of content are not rendered the same to everybody. Right?

    So, how do you think these are so important? What role do style guides and templates play in making sure your contents are consistent across the board with the different teams?

    Betty Mann: Amazing question. Yeah.

    So yeah, there are style guides and templates. I find it essential. A content type is only useful if it’s applied so consistently. And, style guides and templates are sort of the blueprints to do that. So style guides are used to sort of set the expectations like tone terminology rules and, and writing like passive versus active etc. One of my past experiences was I joined a company and they had three names for the same concept. So one was more internal, one was more external, and then one, I guess competitors and other people in the industry were using a different term. And, this was my first job in that sort of industry, and I thought they were all three different things for a good while. And if I think that and I’m on the team you like, surely a user would think that as well. So to make it consistent, so important.

    And then I think templates give writers and potentially devs as well. Like if you’ve got a small team, developers will do first draft, developers will write documentation while of the time. And it would give them a practical sort of framework for each type of page so they can sort of fill in the missing gaps and stuff and hopefully have the same flow as what a technical writer would have. So yeah, it sort of means that when a reader moves between docs, it feels sort of seamless, predictable sometimes, and easy to comprehend.

    Gowri Ramkumar: And yeah, that’s very true. I think, predictability is one thing that, a lot of people would like to see in their content. Right? So there are no surprise elements in different pages when they read. Yeah, absolutely.

  • 10:29 – 12:56 The Role of AI in Evolving Documentation Practices

    Gowri Ramkumar: So Betty, I can’t stop asking this question to almost everybody whom I have as the guest in my podcast.

    So with the rise of AI driven authoring and structured content, how do you see page content types evolving?

    Betty Mann: Fair enough. Anyway, AI was coming, so yeah, it’s on the tip of all tongue.

    So yeah, I find I like using AI tools at the moment. I find that great at generating text, but without the clear structures that I’ve been talking about before, the output can be unfocused or inconsistent. So I think content types are quite crucial to that.

    My boss actually said that, he’s been using an LLM just to sort of like, see, you know, how does doing technical writing. And it seems like a, like an intern, like a really enthusiastic intern. So it tries to bridge the gaps and still makes things up to make things work. Whereas, like we said before, asking those stupid questions and being a human person sort of helps in gaining clarity.

    But yeah, I think, you said, the evolution, the evolution of AI. I think what I’m quite excited about the evolution with AI is that we can make documentation, but then AI could maybe personalize it for each person’s experience, and maybe having dynamic pages with like examples, which are very relevant to each use case and things like that. I feel like the content types would still be the building blocks of that, and they could be like maybe sliced up or split up and then like on a page, you know, maybe it’s a concept, an action, another concept and action sort of thing. But, it would be good to sort of give it to the user when they need it, like maybe anticipate it. Yeah.

    So basically I think like chatbots and things do that as well, like AI takes things and just sort of maybe rewards it more for your use case. But yeah, like I guess from the hackathon that I mentioned earlier as well, we also saw the experience of the user changing depending on their experience of the technology or whatever. So a beginner could maybe use some concepts and get started, whereas an engineer would have like here is your bespoke API call or something as an example. Yeah.

    Gowri Ramkumar: Great.

  • 12:56 – 16:33 ⚡Rapid Fire Round

    Gowri Ramkumar: I think we are now to the rapid fire round of questions.

    Thank you for answering all my other, the first half, it was really you did go deeper in as well. So, let me just move to the rapid fire round.

    Any documentation related resources that you would like to highlight that you thought was fantastic and helped you in your journey?

    Betty Mann: So Vale linting. I’ve loved so shout out to Vale.

    But basically, I’ve been using that, to sort of implement the style guide. So after you download the rules, it’s very easy to say you do this, but will everyone read it or will anyone know it’s there. Yeah. So looking that up with GitHub or something so that when someone does do a pull request it will actively be like suggestion use active voice suggestion, don’t use we you know or use you use is doing it. So I’ve been sort of setting that up and it’s very what’s it called. You can make it very bespoke. So for your own style guide like you can also I think you can take like Microsoft Style Guide, which I think quite a lot of people based on their style guides of sometimes. But you can make your own rules. So, you know, if you don’t want to use a certain word, you can tell it to not use, you know? And then developers also, it sort of doesn’t block them. They can iterate on their things if they are writing a first draft with these in mind. So it’s sort of, yeah. So it frees up tech writers time from like spelling grammar, potentially.

    Gowri Ramkumar: Nice, great. Now, one word that comes to your mind when you hear “Documentation”?

    Betty Mann: Instructions.

    Gowri Ramkumar: Okay.

    Betty Mann: I guess, I don’t know, that’s the correct word?

    Gowri Ramkumar: Yeah. I mean, anything that comes to your mind, that’s it.

    Betty Mann: I think maybe it’s depending on what I’ve been this today I’ve been working on step-by-step guides. So yeah, to me I’m like it’s instructions. It’s like they’re Lego, you know, like the little manual you get with the Lego.

    Gowri Ramkumar: Yeah, yeah, yeah.

    Like okay, one piece of advice that you would give to your 20-year-old self?

    Betty Mann: I think that’s a very good question. I’ve not thought about that. I think, yeah, I guess I was worried when I was 20 again, like, I wanted to do a bit of everything. I didn’t know what I wanted to do, but, you know, I guess my advice would be that there are jobs where that is beneficial, like there are jobs where you can contact, switch all day, hyperfocus on some things, sometimes, talk to loads of smart people and, have a little bit of everything. So I guess it worked out. But yeah, don’t settle for, you know, a job which doesn’t give you that. Yep.

    Gowri Ramkumar: Very nice. Fair enough.

    Okay. I think you’ll be very pleased to know that we’ve come to the end of the podcast, Betty. So, it was amazing to know where you started and how you, got into different opportunities and where you are now. It’s amazing. Amazing to know, all the very best for your current projects. Whatever you’re building I hope it all goes well and for your future engagements too. So and if anything else you would like to add?

    Betty Mann: Just thank you so much for this experience. It’s amazing. Thank you so much, Gowri.

    Gowri Ramkumar: Thank you, Betty, for sharing your experiences as well. Have a great day. Thanks!