Why Aesthetics Matter in Technical Docs with Richard Rabil, Oracle

Transcript:

• 01:16 – 05:12 Richard’s journey into Technical writing

  Gowri Ramkumar: Good day everyone. Welcome to the Knowledge Base Ninjas podcast. Today with me I’ve got Richard Rabil, Principal Technical Writer at Oracle.

  Hi, Richard. How are you doing? 

  Richard Rabil: I’m good. Thanks, Gowri. Thank you for having me on your podcast.

  Gowri Ramkumar: Thank you.

  So, Richard, ample years of experience in this field. But before we deep dive into any topics, I want to know a lot about you. How did you get into this journey? What made you to think this is a good path to go, and how are you enjoying so far?

  Richard Rabil: Yeah, yeah. My journey.

  So my journey actually started in high school, which is perhaps a little unusual for your average technical writer. Many of whom, you know, learned about the career later after college or kind of stumbled into it. In high school, I was a big time lover of literature. I was a bookworm. I was reading a lot. I loved creative writing. You know, I was fascinated with storytelling with language, that’s definitely the case for a lot of technical writers I’ve met. And I knew that I enjoyed writing, and I wanted to apply my passion for writing in a meaningful way, somehow. But I wasn’t sure what my options were, you know, beyond the usual, you know, journalism kind of career path or teaching English or, you know, copywriting, writing stories, which I wasn’t, you know, these things, I wasn’t, I was kind of interested in, but wasn’t quite sure how I would pay the bills with them.

  And, you know, one day I was talking about this with my dad, and he told me that there was this strange breed of writers called technical writers. And I remember being surprised and curious. And so I investigated this a little bit. I found out that the mother of one of my good friends happened to be a technical writer. So I started talking to her about it. I did some basic, really minor intern work for her, and I even tried my hand at, like, writing some manuals for the se for one of my high school jobs and, but I still, like I wasn’t convinced, I wasn’t sure this would be my ultimate career path..

  So, you know, I went to college. I did know that I wanted to major in writing, so I pursued a degree in professional writing. And, I came really close, actually, to pursuing a career in journalism. I enjoyed working for the school paper. I came really close to exploring job opportunities with NPR. But I was applying all over the place to internships, and it so happened I got, offered an internship with a health care IT firm as a tech writing intern, and this was a company that was really close to my home in Maryland. And so it was just practically speaking, it was a really good fit for me. And so, I worked for them, and I liked the company’s mission. They were supporting, you know, health care research around the world. I did some good projects with them. They ended up hiring me after college.

  And, around that time, I also decided, all right, I’m now doing this work full time. I think I’m going to apply for graduate school at Texas Tech University for their technical communication program. And so, from there, I was pretty. I was pretty all in at that point. And, you know, I’ve been in the field for 15 years now, more than 15 years. And I’ve worked for two, you know, IT technology government contracting firms. I’ve worked at a company called Opower, they were a startup, which got bought by Oracle. And so now I am a, you know, I work for Oracle global, you know, one of their utilities business units and document software that helps people save energy. So I get to write for living. Yes. And I support a great mission. o I can hardly ask for more.

  Gowri Ramkumar:Great. What a great journey, Richard.

  Absolutely 15 years of experience. I’ll try to squeeze as much as possible in the next 10 to 15 minutes.

• 05:12 – 13:00 Defining Beauty in Documentation

  Gowri Ramkumar: Now, coming to the aesthetics and beauty matter in documentation, why do you think it’s an important aspect?

  Richard Rabil: Yes. Let’s get into it. This is.

  Gowri Ramkumar: Yeah.

  Richard Rabil: I’m really excited to talk about this. There’s, there are a few points, actually, there’s a lot of points I would love to make about this.

  Gowri Ramkumar: Yeah.

  Richard Rabil: And to start, I’ll take a step back and consider the skeptical stance towards beauty and aesthetics in documentation, because your average technical writer, I think, might hear this question, you know, the people who listen to your podcast and they might think, well, you know, beauty that’s kind of a bloated term for what we do as technical writers.

  And they might hear this question and think, all right, so good design matters. Good. You know, like having an attractive document is an important thing, but ultimately it’s not as important as the content itself. It’s not as important as the words themselves, the accuracy of the content.

  What matters is that the user gets the answer to your question, or they finish their task and they perform it correctly. You know, other things I can easily imagine other writers saying it’s like, you know, we’re writers, we’re not designers or artists, and oftentimes we’re using templates, right? We’re starting from a template, a predefined color scheme, and we don’t have a lot of control over that. And so also you might be constrained by the templates your tool has too. And there’s maybe there’s not much you can do to change the templates that come out of your tool. Or you can do some things, but it requires a lot of advanced skill. Okay. So those are all really valid points.

  And my answer to that is multipronged. So first what I would do is define more clearly what I mean by beauty in documentation. And let me begin by stressing what I don’t think beauty and documentation is. I think it’s actually impossible for documentation to achieve the, what you might call the artistic sense of beauty. You know, beauty in the purest sense of aesthetics. Like, you know, Oscar Wilde famously said, all art is quite useless in his preference to his classic novel, The Picture of Dorian Gray. And what he meant by that is, art, fine art, should not be subservient to a practical or political function. It should be free to be its own thing and to be judged for its own beauty, its own form, without respect to whether it fulfilled a practical function.

  And for technical writers, that’s obviously not true. Like, we have to fulfil a practical function. So when I say beauty and documentation, when I think when I argue that technical writers should care about bringing beauty to their documentation, I’m not talking about the purest fine art sense, like we do have to care about how useful our documentation is.

  So where does that leave us? Broadly, I think that beauty in documentation is kind of analogous to the code is poetry concept that you sometimes hear from programmers who seem to be suggesting that code, like poetry, can be constructive creatively, right? It can result in something concise and elegant and efficient and sort of like how poets pack a punch, you know, in a stanza or in the verse they’re writing.

  So, I think the same is true of docs, like in the sense that you can think of docs in artistic and aesthetic terms. And to get even more specific, by what I mean there, I can think of no better explanation an this piece of writing by – I’m going to really get the name wrong. So I apologize to everybody who’s listening. Daniele Procida, he is the author or the mastermind behind Diátaxis. It’s, for anyone who’s unfamiliar diátaxis. It’s like a framework or an approach to creating structured documentation.

  Gowri Ramkumar: Alright.

  Richard Rabil: Yeah, kind of like the data framework. On his website for Diátaxis, he has written a manifesto of sorts, or, like, a theory towards quality and documentation is what he calls it. And he makes this great distinction. And I’m going to quote him here a little bit. He breaks quality down into functional quality and deep quality.

  Gowri Ramkumar: Okay.

  Richard Rabil: And so by functional quality he means we need documentation to meet standards of accuracy, completeness, consistency, usefulness, and precision. You know, all the things that your pragmatic technical writer who’s perhaps a skeptic of beauty, those are all things they would agree to like, yes, it has to be complete, it has to be consistent, and it has to be useful. But what procedure goes on to argue is that, it’s not that’s not enough. That’s not sufficient, he says.

  And he says true excellence elevates documentation to what he calls deep quality, which means feeling good to use. It has flow. It fits user needs. It is beautiful to look at. It anticipates what the user is going to need next. So I think that’s such an excellent articulation. And I would argue that this is what beauty and documentation really means. And the key point it’s really, really fundamental. And that he, that Procida stresses is that you can’t have deep quality without functional quality. So you can have functional quality but not necessarily deep quality. But he says if you really want deep quality, if you really want to create beauty in documentation, it has to be clear, concise, useful, accurate and correct and all that stuff.

  Gowri Ramkumar: Right.

  Richard Rabil: So, that’s a long -winded answer to your original question, which is, why?

  And I would say because holistically understood beauty, like an approach to making beautiful documentation, puts the user first and recognizes the complexity of human nature. Right? It recognizes that users, you know, aren’t just rational, brings on a stick. You know, they’re people who respond to emotions as well as visual stimuli, and, additionally, the other thing that I think is so important to remember is, as technical writers, perhaps more than any other type of writer, we are dealing with a lot of visual components in our content. So, you know, I’ve listened to other guests on your podcast, and they all come from, they all have tech writing jobs at different companies, and they’re all dealing with not just not just content, not just words, but lists, tables, headers, footers, tabs, navigation systems, headings, and, you know, all sorts of visual components that are kind of on the scale or the continuum of visual design, everything ranging from, like, textual to more graphical and visual, right?

  And I think that’s like a little bit different from like what a journalist or like a copywriter or an English teacher deals with. They’re primarily dealing with essays or, you know, long form or where the copy itself and tech writers, I think, tend to have a lot of, decisions to make with respect to how their content looks more so than the average writer. And so even if, even if we’re using a template. So we were talking about this objection of like, well, I’m just, I’m using templates. How much control do I really have? It’s like I think, even when we’re using templates, we’re still making a lot of choices within the confines of that template. And so, so those are some of the reasons, I think that it’s such an important concept and it’s so important to have a good thought process behind.

  Gowri Ramkumar: Absolutely.

• 13:00 – 18:17 GenAI and the Future of Documentation Design

  Gowri Ramkumar: Now that makes me to think, how does GenAI change the way we approach visual designs?

  Richard Rabil: Yes, yes, we need to go there. That’s an excellent question.

  I thought about this, and there’s a definite sense in which I wish I had a crystal ball because there’s a definite sense in which I don’t know. And there are other tech writers who are perhaps more well researched and have experimented a lot more with GenAI in this respect than I have. And I want to do more research and experimentation. And this is a really good question because when we consider GenAI and how it works, it seems like everything I’ve just said matters less. Right?

  Because if a GenAI chatbot, becomes the defacto interface for how users interact with documentation and presumably the way that you are designing things and you know the aesthetics behind it all, it matters less, because a Large Language Model doesn’t really see things the way we see it. Right? They don’t, you know, an AI chatbot doesn’t really look at layout or typography. It doesn’t process it the way a human does. So it’s like they are sending back, when you ask a question, they’re sending back textual, mostly textual answers to your questions. Right?

  So having put forward all of that and having said all of that, I don’t think the advent of GenAI is going to massively disrupt the need for high-quality, attractive documentation, at least not in the sense we’ve been discussing. For one thing, for the foreseeable future. And this is perhaps a less significant point than others, but the AI chatbots are going to link to the source docs right where they get their content. This is, maybe it’s not true of every AI service, but certainly most of the ones I’ve seen and used. They have a link to where they got the information. And if you’re like me, maybe not all the time, but you know, there’s a good number of times when I still click through to the links. And I think for the foreseeable future, that’s what users are going to do there. They are still going to click through to the source docs, and especially if you know you’re concerned about the accuracy of the answer you’ve gotten or whatever you want to read more. And when your users get to your docs, you still need to have quality, well-designed content waiting for them.

  Within that same vein that, you know, I think of a blog post by this other technical writer. Again, apologize if I’m mispronouncing his name. Fabrizio Benedetti, I believe, who he wrote a post about this question, but he was writing it more from the writing standpoint. Not necessarily a design standpoint, but I think it still applies. I think it’s still relevant. He basically argues that our mission in writing quality content doesn’t change that much in our in the age of AI and he writes, here’s a bit of a quote here. He says everything a user is supposed to see, test, try, know, read and wonder about, or ask is something that an AI is supposed to be concerned about. And that includes tables, diagrams, figures, videos, code snippets, and all forms of technical communication. And he argues that altering your content to satisfy the needs of an LLM not only does this a disservice to human readers, it also poisons the AI well, end quote. So he’s basically saying the best way to create content in this moment of AI prevalence, right? Or rising AI prevalence, you might say, is to keep focusing on writing and creating quality content that can be consumed. And there’s still meant for a human being that’s going to meet human needs. And but he does add some interesting nuances because he doesn’t say, we don’t have to consider this.

  He does say that we have to put, or we have to think about how our content is tagged, for example, to give greater assistance to a Large Language Model that’s looking at our content, we should think about exposing or tagging our topics or sections of content with metadata or with more semantic content, like, for example, if you’ve got images and diagrams, writing really quality alt text, or for your tables, you have to write good descriptions for what the table is communicating so that these tools can, not only look at the content itself on your page, but also look at the meaning behind a table or behind an image. And so it gets a little bit into the accessibility discussion as well. Like this is going to actually force us to consider accessibility and what we need to do for, people who need more assistance. And so he does say that, that’s one thing that, we need to be worried about is like the packaging, not the not necessarily the quality of the content that’s going to stay the same. Our mission is going to stay the same. And I would argue I would extend that and say concerns about design and aesthetics are going to stay the same. But we do have some additional things to think about for, how it’s packaged and how it can be read by LLMs.

  Gowri Ramkumar: Right.

• 18:17 – 22:00 Balancing Clarity and Aesthetics in Documentation

  Gowri Ramkumar: My last question before we move to the rapid fire round is how does one strike the right balance between the clarity and aesthetic design in documentation?

  Richard Rabil: Yes, balance. This is the million-dollar question, Gowri. Yeah.

  Gowri Ramkumar: A difficult one to achieve as well. Right? Like people focus more on the contents than the aesthetics. Sometimes they do a lot of the aesthetics and less on the content. So it’s a, important balance.

  Richard Rabil: Yes. Yes, exactly. And it’s, this is very real tension. And so I do think that it’s a complex question.

  It’s interesting, I think on one level, I have kind of a cop out answer. On one level, the cop out answer is I don’t actually think clarity, focusing on clarity in your documentation is necessarily at odds with creating a thing of beauty. And it kind of goes back to my definition earlier, or rather, you know, that’s the framework or the theory earlier of functional quality and deep quality. If you’re focused on functional quality, that’s important. And that’s essential. Like that should always be part of our core mission as technical writers. And I think that, you know, I would add that any documentation that is unclear, I don’t think it’s meeting that the criteria of then being a thing of beauty. So that’s kind of like a cop out answer, you know, you would it’s like saying, you know, you can kind of focus on both at the same time.

  But there are practical questions, right? Like, we all get stuck in our work and we’re thinking, man, I’d really like to I has to make this update to this section of a document right? And I’m finding these other sections of the document that need updates as well. And I want to make it even more well-designed and more clear. But I have like ten other tickets that I have to do. And, or maybe you’re updating a document that hasn’t been worked on in a while and it’s kind of falling behind the standards that you’ve defined for your other documents. And you’re like, I really want to spend time updating the design of this to make it look better or even like if, if we’re talking about something even bigger, like, maybe all of your documentation you feel is lacking in some respect from a aesthetic standpoint, from that deep quality concept that we were talking about. And you just don’t have time to do this massive overhaul, right?

  Gowri Ramkumar: Yeah.

  Richard Rabil: So I think that, you know, I think the first an important first step is to realize that even if you’re unable to spend time changing global elements or modify the CSS or improve those other sections of the document that you really want to improve, even the act of writing a clear and user friendly procedure, even the act of just focusing on that one update you need to make. Or maybe it’s a smaller document that you need to create. It’s not quite as big as another one. And really, it’s just you have to focus on the writing more. I would say that even writing and crafting sentences and paragraphs that are clear and easy to read, you’re still immersing yourself in the process of making a thing of beauty.

  I would argue there’s not too much of a strict separation there. But then, you know, even maybe you can’t go as far as you want in a given project in which case there’s like a larger question of how you plan with your team, how you plan with your manager, and.

  Gowri Ramkumar: Nice one.

• 22:00 – 28:25 ⚡ Rapid Fire Round

  Gowri Ramkumar: So moving on to the rapid-fire round, Richard.

  You did share a couple of good resources already. But anything else you found very interesting the recent days, particularly on the documentation side?

  Richard Rabil: Yes, What I’ll recommend, I’ll recommend two things. One of they’re both going to be a little bit unconventional for your podcast. On some level, I’ve heard some great recommendations from your guests like about Every Page is Page One. I think somebody came out and talked about Zen and the Art of Motorcycle Maintenance, or maybe somebody referenced that, maybe or maybe I’m mixing that up with a different podcast.

  Gowri Ramkumar: Okay.

  Richard Rabil: Anyways, anyways, definitely

  Gowri Ramkumar: One more resource you mentioned already.

  Richard Rabil: The first I would recommend is it’s actually a scholarly article and it’s called let me find the title, It’s called Supra-Textual Design: The Visual Rhetoric of Whole Documents. And this is an article by Charles Kostelnick. I think I’m getting his last name correct in that. And it’s, you can find it online. You can just search for the title and you get a PDF online. And he introduces this concept of super textual design and what he just means, like transcend it or basically like looking at the global framework, looking at a holistic picture of your documentation, not just homing in on the paragraphs and sentences, but you’re also looking at your white space, your margins, your headers, your footers in the sense of online documentation, you’re looking at your tabs, your color scheme, your navigation, and, maybe your mini table of contents, all of your headings, everything just from global. And then top down. So he’s talking a little bit more about print documentation because this came out and like the late 90s, but it’s still very I would say it’s still very much relevant to what we’ve been discussing today and definitely is easily relatable to online content that technical writers who work for SaaS products documenting SaaS products will need to know. And so, what he, you know, he kind of gets at this idea that I’ve been that. Well, what I would say is it’s related to this point of an integration between functional quality and deep quality.

  The other thing I would recommend is a book called Document Design by Miles Kimball. And what’s really great about this book, this is when I read in graduate school, and they just came out with a second edition.

  Gowri Ramkumar: Right.

  Richard Rabil: What’s great about this book is they discuss at the beginning the concepts of design and the meaning of design, and then they go into very practical chapters on the major components of design, like, you know, typography, layout. And that’s kind of more print-based stuff. But it’s still again, it’s like they have a lot since they have a second edition, they’re also ensuring that it’s encompassing mobile based, online based kind of considerations as well. And they have a lot of really good practical examples. And advice on how to create really beautiful documentation. So that’s another resource I would recommend.

  Gowri Ramkumar: Lovely. That’s a lot from, from this podcast, Richard. Now just only one word that comes to your mind when you hear “Documentation”?

  Richard Rabil: Yes. You know, I think of I think of the word helpful. I think it’s a little bit I really like how your other guests have answered this question, and they’ve talked about useful, they’ve talked about clear, they’ve talked about concise. And, for me, those, those concepts kind of all roll up into this larger

  idea of we, we’re here to help other people. Right?

  And so I think of the term helpful encompass as encompassing this, you know, range of concepts and fitting to the needs of the user and even making, you know, making the content that we produce attractive to the user. So, at the end of the day, that’s the kind of documentation that I want to produce

  in which I think, as technical writers, we should be creating.

  Gowri Ramkumar: Nice.

  A piece of advice to your 20-year-old self?

  Richard Rabil: Let’s see, I think I would tell my earlier self, my younger self, to ease up on the really advanced stuff in technical writing in particular, I’m thinking of content reuse. Content reuse is really powerful. And I think it’s a great tool in our toolbox. A lot of help authoring tools and wiki tools provide some kind of content reuse capability. And when I first learned about this, I was really excited. I was very, gung ho about reusing as much content as possible. And but it has, it has its downsides. It’s very it can become very difficult to maintain. You’ve got to have IDs for all the pieces of content you create. You’ve got to make them all easy to find. You don’t want to duplicate it. You don’t want other team members to duplicate it or to write a similar, you know, snippet of content. And then now you’ve got two that are floating around and you have to decide whether you really need both of them and how you retired one if you don’t need the other. So, it actually ends up if you go too far, it can create so much overhead

  that it’s just more you’re spending more time on the overhead than you would if you just didn’t use it in the first place. So I think I would, I think I would tell my younger self to, be more conservative with that approach, to still recognize that there’s a great place for it, but it requires kind of an artistry and a very

  careful planning behind it.

  Gowri Ramkumar: Nice.

  So I think we are, with that, we are at the end of the podcast, Richard, and it was lovely talking to you and oh my god, that’s a lot to observe and taken but very, very useful. And I would say really, honestly, it’s a different way of thinking how a documentation should exist.

  Richard Rabil: Right, right. Well, thank you so much for having me. This was a real pleasure. Thank you, Gowri!

  Gowri Ramkumar: Thank you. Have a good day!