Manny Silva: Docs As Tests For Resilient Technical Documentation – Episode 213 Content Strategy Insights podcast

Content provided by Larry Swanson. All podcast content including episodes, graphics, and podcast descriptions are uploaded and provided directly by Larry Swanson or their podcast platform partner. If you believe someone is using your copyrighted work without your permission, you can follow the process outlined here https://podcastplayer.com/legal.

Content Strategy Insights »
Manny Silva: Docs as Tests for Resilient Technical Documentation – Episode 213

6M ago 36:18

MP3•Episode home

Manny Silva Technical documentation of software products is critical work that needs to accurately inform end users, regardless of how quickly and substantially the software might be changing. Manny Silva has created the Docs as Tests, a system that integrates a set of well-developed practices and a collection of engineering tooling, to help technical communicators streamline and constantly improve their software documentation work. We talked about: his work at Skyflow and his new book "Docs as Tests" and a new version of his Doc Detective software the variety of "docs as" strategies that have emerged in technical documentation the intent of Docs as Tests to validate the accuracy of documentation the principles that underlie his approach to documentation the truism that in software "something always breaks" and the way Docs as Tests addresses this issue the tools available to test documentation the origins of his Doc Detective tool, which integrates developer tools in a tech-writer-friendly package how he extracts content and code from documentation to test it the differences between his old and new ways of validating the documentation he creates some examples of his Docs as Tests workflows, as well as other organizations doing similar kinds of of testing a key insight in the development of how to present Docs as Code to other tech writers the support and excitement he has seen in the tech docs community for his tools and others' Manny's bio Technical writer by day, engineer by night, and father everywhere in between, Manny wear many (figurative) hats. He's passionate about intuitive and scalable developer experiences, and he likes diving into the deep end as the 0th user. Here are a few things that keep him busy: Head of Docs at Skyflow, a data privacy vault company Author of Docs as Tests: A Strategy for Resilient Technical Documentation and the Docs as Tests blog Creator and maintainer of Doc Detective, an open-source doc testing framework AI development and experimentation He's always looking for collaborators on his projects, and he loves chatting with folks, so don't hesitate to reach out. Connect with Manny online LinkedIn Docs as Tests Doc Detective Video Here’s the video version of our conversation: https://youtu.be/zPkjrG1zgHg Podcast intro transcript This is the Content Strategy Insights podcast, episode number 213. As software has evolved from occasionally updated, shrink-wrapped artifacts to complex, continuously evolving online products, technical documentation practices have had to adapt. Manny Silva's contribution to this evolving technical landscape is the idea of Docs as Tests, a set of practices and a collection of engineering tooling that helps technical communicators streamline, automate, and otherwise improve their software documentation work. Interview transcript Larry: Hi everyone. Welcome to episode number 213 of the Content Strategy Insights podcast. I am really delighted today to welcome to the show Manny Silva. Manny is the author of the forthcoming book, Docs as Tests, and that's what we're going to talk about today. The subtitle of that book is A Strategy for Resilient Technical Documentation. Which he's got a fascinating approach and we'll talk in detail about that. He's currently the head of Docs at Skyflow and he's also the creator of a tool called Doc Detective that we'll talk more about. So welcome, Manny. Tell the folks a little bit more about what you're up to these days. Manny: Thank you for having me, Larry. Well, there's the book that you already mentioned that's going to be coming out shortly. I am working on a new version of the Doc Detective software to come out alongside the book. But otherwise I am handling things at Skyflow, new fun features coming out all the time. I own all of the documentation there, all of the error strings, really anything that's text that it doesn't come from marketing. But outside of job related things, I like to spend a lot of time with my kiddos and they keep me very busy. So lots of life happening all the time. Larry: Never a dull moment, that's a good life to have. But you've chosen, in the midst of all that, to write a book. Which I just admire immensely that anybody who takes on that challenge. More power to you. So first I just want to set this up a little bit. A few years ago, I don't know how long ago this came, the notion of Docs as Code that this theory that you should write documentation the same way you build the software ish. I probably am misrepresenting that. I assume that Docs as Tests might be a play on that, but tell me a little bit about the origin of the book and why you took all this time to write a book about it. Manny: Sure. So I'll start with Docs as Code. Docs as Code is one of many Docs as strategies I've come across as a technical writer. Docs as Code means that we as writers adopt many of the engineering practices and tools for handling our documentation. We use version control to manage our content. We use continuous integration and continuous delivery to check that our content builds like it should and to push it live to our users. But there are other Docs as strategies, like Docs as Product is a way of interpreting documentation as a product that is delivered by the working group. Just like you would your web interface or given feature or whatever else it is that your company builds. Manny: Docs as Tests is another one of these that borrows from engineering. But instead of the underlying tools and practices for managing code porting over to managing content, it brings in the validation aspects. The ways that engineers make sure that their code does what they expect it to, we're now porting over so that we can validate that documentation is describing what we intend it to, that it can work as written, that the procedures are correct and accurate against the products that they're written to describe. Larry: Nice. And one of the things I really liked as I read the book was that this is like tech and platform agnostic, which makes sense because there's so many ways that people can document software. Manny: Yeah. Larry: Like you just said, there's a number of philosophies and theories and then there's specific tools like DITA CCMSs or just a regular old CMS or probably a million spreadsheets out there that people are using. So that just points the need for a principles-based approach. Can you talk about the principles that underlie this approach to docs? Manny: Sure thing. I mean, you hit on one of them already. That Docs as Tests is platform agnostic, tool agnostic, format agnostic. If you use DITA, great, you can do Docs as Tests. If you do Docs as Code, you can do Docs as Tests. The tooling that you choose to implement Docs as Tests will vary by whatever constraints you have in your workflows. But Docs as Tests as a strategy works broadly. And as far as the application of it, there are a few core tenets that really help define what makes Docs as Tests work. The first is a pretty straightforward assumption that docs are inherently tests because docs are assertions that a tool is supposed to work a certain way, and I'll give an example here in a moment, but assertions are inherently verifiable. They are testable. And so if docs are assertions and assertions are testable, that means that docs are tests. Manny: So when you reference a product behavior or an attribute like a button label, you make a literal, verifiable assertion about the product. When you write the procedural step click continue, you assert that there is a visible clickable button that has the label continue. This statement is either true or it is false, and it can be assessed by performing the procedure. In engineering, assertions are used in tests to verify code-based behaviors. Tests are assessed whenever they're run, usually when the code changes. For content owners, our docs are our tests. Our product references are our assertions and our test runs are performing our procedures. And if we don't test our docs ourselves, we are making our users test our docs for us. They get tested one way or another and it usually ends badly if your users test your docs. Larry: Yeah. No, I just had a thing yesterday where I was screaming at my computer, and screaming at probably your poor colleague at that software company. One of the things about this is everything changes so quickly now, you don't buy software in a package and then a year later it's updated. You already mentioned continuous integration, continuous deployment. So I assume that's one of the drivers of this as well, just that relentless pace of change. Manny: Yes. Because I mean part of how this all came about was before Skyflow, I worked at Google. Before Google, I worked at Apple doing technical writing. And something always breaks, something always breaks. No matter how good your communication lines are with your colleagues, how frequently you check in, what procedures you have in place, inevitably something will slip through the cracks. A button label changes or your design team decides they want to change the shade of a banner from green to blue and it makes all of your screenshots go out of date. And so suddenly everything that was great before is no longer. And a user goes in to look at your docs and it no longer reflects the product interface that they're interacting with, which undermines their trust in your docs, in your product, in your company as a whole. Manny: We've all had experiences with docs that were inaccurate. By making sure that our docs are accurate, by actively testing our docs against the product interfaces, we not only avoid undercutting trust, we actively are building trust with our users. Because as they see that, oh hey, time and again these docs work the way I expect them to,

134 episodes

#Business #MBA #Content Strategy #Larry Swanson #User Experience #Tech #Software Development #Podcasting Education