Writing Documentation for Humans and AI: Insights from Sakshi Shah, Tesla

Transcript:

• • 01:21 – 04:15 How Sakshi Found Her Way into Technical Writing

    Gowri Ramkumar: Good day, everyone. Welcome to the Knowledge Base Ninjas Podcast. Our guest today is Sakshi Shah, Technical Writer at Tesla. Hi Sakshi, how are you doing today?

    Sakshi Shah: I’m good. Thank you for asking, Gowri. This is a very good opportunity, and I’m excited to be here.

    Gowri Ramkumar: Fantastic. I think you’ve got six plus years of experience in this space. I want to rewind a little bit and ask you how you got into this field. What motivated you to choose this career path?

    Sakshi Shah: That’s a very good question. My journey into technical writing has been a little up and down. It’s not a very conventional way of getting into technical writing. This journey started almost six and a half to seven years back.

    I had just graduated from my MBA school, and I got my first job in training and development. There, I was writing training manuals and training content. That’s when I realized I really liked writing content that helps people in an easy-to-understand manner or teaches them something.

    I did some research and came across the field of technical writing. I did a course in technical writing, and ever since then, I’ve been working as a technical writer.

    In my next company, back in India, I was unexpectedly thrown into user testing. While doing user testing, when I saw users fail or succeed, I really understood the importance of having good documentation. I saw how good documentation helps users and how bad documentation impacts them.

    That’s when I decided to do a master’s degree. I came across the field of Human-Computer Interaction, or HCI. I came to the US and studied human-computer interaction in California. I took a lot of research courses and studied human-centered design.

    I wanted to use that knowledge to write good documentation and make my content more user-centric. That’s how I came into technical writing, and I’ve been a technical writer ever since.

    Gowri Ramkumar: Wow, that’s great. So, experiencing how users benefit from good documentation is what motivated you to choose this career?

    Sakshi Shah: Yes, that’s right.

  • 04:15 – 06:29 From One Audience to Two: Humans and AI

    Gowri Ramkumar: How has the role of documentation changed over the last seven years with the rise of AI, chatbots, and search assistants?

    Sakshi Shah: Traditionally, documentation was written only for human users. We wrote with the perspective that a human would be holding a manual and using it. But since AI has come into the picture, we now have two audiences: human users and AI assistants or chatbots.

    When you write for AI, things change. AI does not understand content the way a human does. When writing for humans, we often assume things that users might already know. But AI is not good at reading between the lines.

    It is also not efficient at understanding large blocks of text, huge paragraphs, or inconsistent naming, like using three different names for the same tooltip. So we have to be much more specific when writing for AI.

    This means chunking the data into smaller portions, being clearer and more precise, so the AI doesn’t hallucinate or skip steps. That’s how the role of documentation has changed.

    Does that make sense over here?

    Gowri Ramkumar: Yeah, so the main point is breaking content down into simple context so AI can interpret it easily.

    Sakshi Shah: Yes, exactly.

  • 06:29 – 08:50 Understanding Users Before Writing Documentation

    Gowri Ramkumar: What challenges arise when content is optimized only for human readers? So we spoke a lot about how to make the content more acceptable for AI, but then how do you optimize it for human readers?

    Sakshi Shah: So you mean, how do we make the content more efficient for human readers?

    Gowri Ramkumar: There could be a lot of challenges that could come right? Or put it other way, how do make it easier for the human readers?

    There isn’t one best method, but over the years, we’ve learned that understanding your users is key. You need to know what they need from the documentation you are providing.

    The first thing technical writers learn is to understand who their users are. Are they novice, intermediate, or experienced users?

    Once you understand that, you gather information and arrange it in small, easy-to-understand pieces. Based on the user type, you decide how implicit or explicit your content should be.

    For example, for novice users, you might need to explain tools, add more definitions, glossaries, indexes, or FAQs. For experienced users, like developers, you don’t need to define everything. They want to know how to use the product, how to work with code samples, or how to interpret annotations or tooltips.

    That’s how you gauge user needs and make content simpler, easier, and more usable.

  • 08:50 – 10:19 Granularity and Metadata in AI-Ready Documentation

    Gowri Ramkumar: So you spoke a bit about how we can make the content more AI-ready, while focusing on the humans as well.

    Are there any core elements of truly AI-ready documentation?

    Sakshi Shah: Yes. To make content AI-ready, you need to focus on two things: granularity and metadata.

    AI-ready documents are always chunkable. Instead of one giant wall of text or storytelling, you break content into smaller sections like FAQs, troubleshooting tips, or specific definitions.

    Clear metadata labels help machines understand exactly what they’re looking at.

    For example, a clearly labeled pile of clothes is easier to understand than a messy pile. That’s how chunking and labeling data at a granular level helps AI.

  • 10:19 – 12:47 What Is TOON and Why It Matters

    Gowri Ramkumar: Now this is something that I have not come across a lot, but hopefully you can help me. What is token-oriented content in simple terms?

    Sakshi Shah: That’s a great question. It’s a newer concept called TOONs, which stands for Token-Oriented Object Notation. It’s about cutting noise so AI can focus on the signal or substance.

    AI reads text in small chunks called tokens. Traditional documents often have large paragraphs, storytelling, repetition, and formatting tables and so on that help humans, but not machines. It becomes hard for the machine to read and interpret.

    TOON structures content in a very clean way, stripping unnecessary fluff and making rules and relationships explicit. This helps AI parse information without guesswork, retrieve the right information, respond accurately, and use fewer tokens in the process.

    Think of it like a recipe. Human-only documentation is like a long blog post about a grandma’s kitchen. TOON style is just a list of ingredients and numbered steps. The AI doesn’t really need a lot of storytelling. It just needs the steps to cook the meal.

    Another example is: do this, then a note, the reason, and the tools used in doing the steps. Break it into two or three steps so AI can understand it better and use fewer tokens.

    Gowri Ramkumar: I like the way you come up with the examples. That was very easy to understand and interpret.

  • 12:47 – 14:50⚡Rapid Fire Round

    Gowri Ramkumar: Let’s move to the rapid-fire round.

    Any valuable documentation resources you’d recommend?

    Sakshi Shah: Yes. One book is Docs for Developers, which gives practical software documentation guidance.

    I recently read it and found it very helpful.

    I also recommend the Microsoft Writing Style Guide. And finally, the Write the Docs community.

    They have a Slack channel where you can connect with other technical writers.

    Gowri Ramkumar: That’s great, thank you. One word that comes to your mind when you hear “documentation”?

    Sakshi Shah: “Foundation”. It’s the source of truth, not only for humans but for AI systems as well.

    AI cannot function properly without a solid foundation.

    Gowri Ramkumar: One piece of advice for your 20-year-old self?

    Sakshi Shah: Treat curiosity as a career skill. Always be curious, keep learning, explore new resources, and don’t be afraid to publish your work.

    As new writers, people are often scared to put themselves out there.

    Don’t do that. Put your work out, take feedback, and improve. Never leave your curiosity.

  • 14:50 – 16:10  Closing Thoughts: Why Technical Writing Is Not Going Away

    Gowri Ramkumar: Is there anything else you’d like to share with our audience?

    Sakshi Shah: Yes. Even in the age of AI, technical writing is not dead. It’s becoming more prominent.

    Technical writers are becoming the source of truth for what information goes into AI.

    We are now becoming the architects of architects, not just writers. Our role is evolving with the change of AI. But it would never go away.

    Gowri Ramkumar: Thank you. This was really helpful. I think it’s needed at this hour.  

    All the best for your upcoming projects. And it was great talking to you.

    Sakshi Shah: Thank you. Yes, Gowri.