KMoesif’s Podcast Network: Providing actionable insights for API product managers and other API professionals.
To help you fend off documentation from being the Achilles heel of your API product, we have a thirty-year veteran of technical writing on our podcast today. Charles Miller is currently the lead content strategist for APIs at Medidata Solutions, a Dassault Systems company.
Charles fills us in on how to create outstanding technical documentation, what is the plain language principle and why it’s so important, what standards and guidelines you should follow, when to use the active voice, and many more.
Derric Gilling, Moesif’s CEO, is your host.
Make Your API Platform Successful with Moesif!
Transcript
Derric Gilling (Moesif): Welcome to another episode from Moesif’s API’s over IPAs podcast network. I’m Derric Gilling, your host today, and the CEO of Moesif, the API Observability platform.
Joining me is Charles Miller, the lead content strategist for APIs at Medidata Solutions, a Dassault Systems company. Charles is a multiple award-winning technical writer and leads document creation for APIs at his company. Really happy to have you here today.
Charles Miller (Medidata Solutions): Thank you Derric.
Derric: Definitely. So just getting right into things, I’m curious what’s your path to writing documentation for APIs, and as a follow up to that, how did you transition from hanging out with Allen Ginsberg to writing award-winning technical documentation?
Charles: Well, that incident was definitely in the past. I hung out with them once, so don’t want to give necessarily a wrong impression. But, you know, it was fun. You know it was a long road that led me from writing the Great American Epic poem, if you will, to realizing that I needed to meet my family’s needs and not just my own.
So my first step was to find a job where I could meld my interest in writing and technology. And so I had to go back to school for technical writing and editing classes. After school, I spent a lot of time at the beginning of my technical communication career working as a consultant. Actually for about 10 years I was a consultant on and off. And as many people know who’ve done consultancy, that can be pretty stressful. Where you have a job that maybe goes on for a year or maybe half a year, and then it ends and then you have to look for further work. But I was lucky, I had pretty steady work. So even though it was stressful, a little bit of digging taught me many avenues to learn different approaches to documentation, the experience taught me how to collaborate with many different audiences and kept me up to speed on the technologies. So every job I went to I was able to accumulate new knowledge about technology, and fortunately it was all new technology to me anyway. So, by the way, I didn’t create the Great American Epic poem, but I was able to have some of my Poems published in two anthologies.
Derric: So speaking about your approach and all the knowledge that you’ve accumulated over the years, what is the number one takeaway for any of our listeners on how to create outstanding technical documentation?
Charles: Well, as everyone knows, I’m sure, it’s all about time. Time is our enemy and sometimes perhaps our friend. But often it’s a deadline crunch. So the more you have of it, the better your text will be, in my experience. Your time to investigate and understand the context of the information that you’re presenting and that you’re writing about. You have time to do interviews, and you also have time to write, rewrite and test your documentation. The main test, of course, is always to get documentation in front of the users, so you can gauge its usability. Then if you can, you can perform user surveys and usability testing to gain user input feedback.
Derric: And then when it comes to the changes in API documentation, I know a lot has happened in terms of OpenAPI spec and Swagger and such, how do like auto generation and how do the new technologies play in the major advancements for documentation?
Charles: Well, having been in the business for about 30 years, I can say there’s been huge amounts of change. As people will probably have heard, or maybe even some know, it’s evolved from manually creating technical content in Microsoft Word, to now using content management systems for online consumers. We use Confluence for our major means of deployment. I’ve actually created documentation in HTML, with the text editor, and then uploaded it to the portal via file transfer protocol. That shows you how far back I go. Moving to a content management system like Confluence was major, because it helped us move towards more automated ways to generate documentation, as you said. And then that was consistent with format and brand. We can actually create a consistent message across all of our services, all of our products, because we’re creating a single brand. But, it also allows us to impose and adhere to our writing standards, as well as our programming standards. So, that’s kind of a little bit of history where I’ve been.
Derric: And then can you tell me more where it’s going? What’s next for API documentation?
Charles: I think that what’s next is digital assistance, with AI and the ability to do natural language processing and natural language understanding. I think we’ll begin to see systems (I’ve already seen some at conferences), which are able to take a user’s question and come back with an answer. The answer today might be pretty-much canned, because the system has been set up for it. But in the far, far future, we’re going to be talking about having AI digital assistants skating the database, getting the information and being able to come to semantic conclusions, and presenting answers based on that analysis. I should be able to do analyses of the information and get conclusions based on what it’s been able to identify and scan.
Derric: Sounds like documentation is a lot more than just the text on an HTML site. So what does documentation encompass?
Charles: Sometimes it’s getting out what a system or computer would need to know. So there’s computer-readable documentation, then there’s human-readable documentation. So documentation from my end, even though we do some computer-readable documentation, most of it is human-readable. I have to be able to create text and information that is understandable and usable. Users need to be able to understand the information almost automatically. They shouldn’t have to scan and parse information to figure out what it means. And then usable — if they’re working on a task they should be able to take that information and finish the task that they have set up, or that they have in front of them.
Derric: In terms of making it usable, is there a set of guidelines that you use, or follow, in terms of starting a new project?
Charles: Well, I’m fortunate to work with an organization and in a department where we’ve defined writing standards, and writing standards are key. There are the industry standards: there’s the API manual style, there’s the Chicago manual style, there’s the Microsoft manual style and Apple manual style. So those are good places to start. Anyone coming into the field should obviously be aware of those and know those almost like the back of your hand. But then an organization should take those and develop its own standards. So that’s what really begins the process. And then there are standards on top of that, such as the plain language principles, plain language standards, which really emphasize usability and understandability. So, we incorporate those plain language standards and principles into our own standards. That’s a good place to start.
Of course, you can extend that into usability testing, where some companies have the luxury of doing that. It does take time to do, but it’s invaluable being able to get user feedback. And of course, you’re always opening up your documentation to comments, so users can provide comments about how useful the information is and how usable it is. And then user surveys as well and take that input and modify your information as needed.
Derric: One thing we’ve seen when it comes to documentation is sometimes you have so many different product owners or product teams, your documentation might not be consistent in tone across the whole company. And as you’re speaking to standards, what are some ways to make sure that you have a consistent tone across the entire company?
Charles: Yeah, that is challenging. Certainly you can’t go wrong having those consistent standards. But often you’ll have, for example, business writing standards and we have our technical writing standards. Sometimes people think the business writing standards are different than the technical writing standards. I tend to disagree. I’ve taught business writing and I’ve also taught technical writing. I don’t think they’re that different, but you will find some organizations and perhaps departments that don’t agree. So you have to find the baseline which is again, for me, it’s plain language. Use the plain language principles and stick to those principles where you’re talking about making the information usable, informative and communicate a sense of friendliness, a sense of transparency that you’re giving them the information as clearly and succinctly as you can. I think that in the bigger picture that will begin to migrate to other departments as well. You have to create a consistency within the organization, so your internal documentation should be the same, or should try to emulate what you’re doing for your external audiences. You know it’s a challenge. I’m not going to say it’s not, but standards are definitely the beginning.
Derric: Does this mean there’s like a central team that owns documentation, like a developer experience team? Or should it be up to the various product owners themselves?
Charles: Well, we have a user experience department that maintains their own standards. We work very closely with them and we try to correlate our standards with theirs. And then we have our own department, which is technical communication services, which is devoted strictly to providing the technical information to our users. So it’s user-facing documentation, and I work with within that department. It’s a partnership: you have a partnership with the developers, you have a partnership with product management, you have a partnership with testing, and each one of those should be able to provide input into the documentation. And, as you say, sometimes maintaining the tone with all those voices coming in is difficult. But, it’s not something that you can’t overcome — it’s a challenge, it’s an obstacle, but maintaining your standards, writing to those principles where you use active voice (for me active voice is crucial), that will allow your tone to come across as often being very direct and transparent.
Derric: That’s really good to know the active voice gets your message across a lot better than the passive one. When it comes to keeping these docs up to date, sometimes it could be an afterthought. How do you keep them up to date — you’ve got old screenshots, API specs that are out of date, maybe the version doesn’t exist anymore. And tooling has gone a long ways in terms of stuff like OpenAPI and Swagger, but still there’s a lot of docs out there that are out of date. Do you have any best practices for that?
Charles: Well, the best practices that we use, for API documentation specifically, we use OpenAPI. So that, like you said, really does help us to maintain the documentation, because nothing’s going to change unless the engineers change it and they’re the ones responsible for OpenAPI. We, as technical writers, act as technical editors making sure that the writing, limited to places that there are within the OpenAPI spec, is consistent with our writing standards. So, it’s always a matter of working with your partners. It’s a matter of making sure that you have partners who are willing to create really, really good documentation that communicates with end users.
Derric: And how do you make sure that you’re speaking to the right audience? Sometimes you have developers that are more novice, who are looking for just a Getting Started Guide, and you have other developers that are super experienced and they want to get right to the point and get started? There’s so many different types of developers and flavors of developers out there. Is there any way to structure documentation or practices on that side?
Charles: Yeah, we structured our API portal for example, and I’m going to stick strictly the API documentation for the moment, we structured it around, like you said, being able to provide information to our various audiences. We had newbies (or new users), developers, and really, really experienced developers. We also have managers coming in to look at the documentation saying “Hey, what is this? What is this API going to do? How come I should be interested in this? What am I going to get out of it?”. Testers need to be able to read it and understand it.
So, for example, in the Getting Started Guide, getting started is something where we provide enough information for all developer levels to get started immediately. So we provide things like authentication, authorization information, how to register your API app, so developers can get up and running as quickly as possible. And then of course we provide code snippets. We provide samples of making API calls. I think OpenAPI itself, the specification, is really good about that because it provides the baseline information almost any developer would require to make an API call, to make a request. So, that has also really helped us to be able to reach all of those levels of users that we have.
Then understanding your audience, in terms of how they process information, is important — not all developers process information the same way. So we have some developers look at it from the really big global view, and want to have an entire comprehension of the system as a whole, so they can work their way down to the bottom level and piece everything together and have a clear view of what they’re doing, for whatever reason. Some developers just want to get started right away. In fact, most of your developers are those who want to get started right away and have a specific task at hand. They want to be just able to accomplish that task, get it done and then move onto their next task. So we do provide things like workflows, we call them recipes: how to make a certain call within a specific instance or context — like many developers have to perform certain tasks within our platform. So we identify those tasks and then we provide the steps with links to the OpenAPI documentation which they can get the details from, for making that call to accomplish a series of tasks in order to do, let’s say for example, gets a username or something like that, that’s very basic. But we have more complex tasks that they might perform, where still each one of those steps in accomplishing that task links to a specific type of documentation within the specification.
Derric: Definitely, we’ve seen a lot more of playbooks and recipes, we totally think that’s a great way to improve the developer experience. In fact, I think Postman’s doing a lot of stuff with Collections nowadays, so you can start off pretty quickly. Anything else that technical writers and developer experience experts should be doing in terms of assisting those developers getting started with your platform?
Charles: Well, we would like to begin to get a playground where users can actually make calls inside the documentation itself. OpenAPI does provide that, so we’re working towards that as well. We want to begin implementing a forum so that developers, either customers or internal developers, can ask questions and receive almost realtime answers to. And then we can collect that information and keep it in a database, so that your later users can come in and question the database and receive an answer back. As we move towards digital assistance that type of database will be really, really useful.
Derric: Do you have some best practices on how to start a forum, especially if you’re brand new and you don’t have enough of a community. How do you make sure it doesn’t look like it’s empty.
Charles: Well, since we haven’t developed one, that’s going to be a real question. But like everyone else we’re going to go to Stack Overflow and then steal from them. Just kidding. We have a lot of really good developers who are interested in the customer’s point of view. So I think that we could easily populate a forum once we get it up and running with questions that users will want to know, and will need to know, even. And, in fact, we’re working on that now. We’re moving forward with this idea of recipes of workflows. Identifying those standardized tests, objectives and goals, that most users would need to do to work within our system, and to navigate throughout the platform.
Derric: What about the questions that the developer doesn’t know they need to ask? We talked previously around forums where they have a specific question in mind, or when they’re getting started, but what about things like a new feature that they didn’t know existed, or a new use case? How do you think about documentation from that perspective?
Charles: You know that’s a really interesting question and it’s something that I addressed in my presentation to API:World, which was about context — you have to understand the context. So, a writer has to understand how to provide the information in such a way that a user is going to come away from reading your documentation and be able to ask new questions and come up with their own answers. So, that’s certainly not something that’s easy to do, but it has to be done at least in a more mature user documentation setting. You have to be able to understand the platform, in our case it’s a platform. You have to understand the product, and you have to able to provide that type of information that those users will most obviously, most always, ask. So that they can make use of your products.
Derric: So sounds like having context is really important to know what the person is looking for. Does this mean like static documentation is on its way out and are we moving towards more personalized or, dynamic, docs? What will that look like in the future?
Charles: I think dynamic docs is definitely it, but the context is always going to be there. To me, some people might think of it as reference information, as I presented in API:World. The different types of documentation that developers find include reference information, recipes, code snippets, but this reference information is overview information and I’m not sure that digital assistants could do that at the start. That information has to be provided by someone who understands how all of this fits together and how all of it works. Which is really an encapsulation about what context does and what context doesn’t mean. So there would have to be a human being at the beginning writing all of this, and providing it in a format that a digital assistant could somehow scan through and formulate answers to. So to answer your question, I think written documentation is going to have to at least be there until, well I mean it’s just going to have to be there even for digital assistants. That’s just how I see it.
Derric: Oh, definitely. I mean, you’ve got to have your API reference somewhere, right? I mean, you can’t just have it all through voice or digital assistants.
Charles: Unless they develop AI systems which can begin to actually create information, create context, and that’s something I don’t see happening for a while. I mean 50 years maybe, but who knows, natural language understanding is pretty impressive.
Derric: It will be interesting to see what Intercom and Drip does when it comes to documentation and helping with those digital assistants. Any other tools that you recommend for our listeners besides using OpenAPI and that type of stuff?
Charles: Well, we use Confluence. It’s a really powerful tool. It provides us the ability to guide users and to categorize information. It provides the writers templates that they can use to begin generating documentation. So, for example, we can provide for our developers templates that they can use to begin writing their own recipes. At this point it’s me as a technical writer working with the developers, working with product management, with testers perhaps, to come up with the steps that are required to accomplish a specific goal. What we’re looking at now is to create a template that the developers can take and begin to fill in the steps that are required. And then I, as a writer, would go back through it and make sure that it obviously follows some writing standards and make sure that it fills in all of the holes for what we’re talking about with audiences — “well, wait a minute, maybe this level of audience needs to know this”, “what’s the answer to that question”, or maybe “another audience type needs to answer that question”. Those are the types of things that we call curating information, so we, as technical content specialists, would not be the generator of information, but we would be the curator. We would take the information and make sure that abides by the standards that we’ve set up and then also fills in everything that the customers would need to know.
Derric: Totally makes sense. It sounds like that’s a good way to have the standard and have a good process in terms of developers filling in all the information. But you already have the standard of what it should look like, and look and feel like, right?
Charles: Oh, absolutely. And that’s what Confluence is. It gives us a chance to brand our information and to make it consistent across all of our products.
Derric: Where do other formats like audio, video fit in? We see a lot of folks trying to add different things like Gifs and stuff inside the documentation. Is that important too, or do you think that’s just like a fad?
Charles: I definitely don’t think it’s a fad. I think it’s the future. The future is going to be where you have digital assistants and then that’s going to be melded with either Gifs and/or videos that provide information based on the user’s needs and their context — what context are you working on, what kind of information can I provide that will answer your questions. So video is going to be very important. And then getting it down to the Gif level, where you can go through a tiny piece of a process, will be really, really important. We do have videos currently in our end-user documentation. We do have plans providing videos around integration and how to integrate different products with our product using APIs. So that’s going to be important and I see that as something which is part of the future. Videos are very labor intensive, at least now. We have to get to the level to take away so much of the labor intensity and maybe put it into the hands of developers. There are some of our developers who are really adept at creating videos, as are our testing team. So somehow being able to single source that information, from let’s say testing, and being able to get it out to our external audiences, would be an interesting way to go. But, we have to fit our standards, you can’t just put anything out. To be professional, it has to look professional, has to be branded, etc.
Derric: Makes sense. And then my last question is if you look at all the different companies out there doing some great stuff with documentation, what’s your favorite and what makes it such a great company in terms of documentation?
Charles: Well, my favorite is still probably GitHub. I think it’s so comprehensive and they really do get into the nitty gritty, they answer the questions everyone should know. Some say “everyone should know this, so we won’t document it”, but you can’t take that attitude, even though that’s an attitude that we often still encounter. But GitHub takes the baseline approach — what would a person who’s never worked in our platform need to know to get up and running and to perform specific tasks. And so that’s why I like their documentation. They’ve really thought through all the ramifications of their information, and they’ve also thought through what their different audiences require to make use of their platform and their product.
Derric: Definitely agree. I like what Github has done with their changelog stuff. I think it’s pretty cool to see all the updates to the GitHub platform over the years.
Charles: Well, the last time I checked, and I haven’t checked in a while, but we based our changelog on what they do. I mean, it’s very stripped down, very minimalistic — we change this, we added this, we deprecated that. And then we give links, of course, to any additions in the resources that were changed. Our customers require detailed information and our release notes are pretty extensive for our end-user documentation. It even gets worse because we work in a regulated industry, we have to provide as detailed information as we can, and then our customers are very fastidious about how much information they want. You know, they’re very sophisticated. So we do provide all of that information, we have templates setup. But that’s, again, our end-user information for API documentation. We’ve taken the standard of providing what’s been added, what’s been changed, what’s been deprecated, and then we give maybe a line or two, a sentence or two, of what the change included.
Derric: Funnily enough, we actually based our change log off of Github also, they do just such a good job, like you mentioned, getting right to the point and not adding too much fluff to it.
Well, thank you very much Charles. I appreciate hosting you here on the Moesif podcast. Anything else that you want to add before we end?
Charles: Thank you Derric. Thanks for giving me the opportunity to spend time with you and to talk about something I love very much, which is documentation.
Derric: Well, definitely. Documentation is always super important to help developers get started and make sure they’re successful with your platform.
Charles: Always. We’re customer focused and we try to stay customer focused.
Derric: Well, thank you very much Charles. Have a good one.
Charles: Thank you Derric. You too.
