API the Docs recording: How Trends in API Documentation Differ from other Tech Comm Trends

The following is a machine-generated transcript of the podcast. Expect typos, misspellings, and other inaccuracies from the actual speech.

[00:00:00] Hi, my name is Tom Johnson, and today I'm going to talk about how trends in API documentation differ from other tech com trends. Um. At the turn of the year, back in December, I was kind of sitting around thinking that I wanted to write a post about trends, and I was trying to come up with what to say.

[00:00:24] And I started looking at what other research had been done around trends. What did people already written? And I looked at existing surveys. Uh, there was a. Uh, tech comm census by Saul Carliner. That was very extensive across the broad tech comm industry. Another really good survey by Scott Abel, a benchmarking survey, but I was a little frustrated by some of the results in these trends.

[00:00:51] It looked like, uh. The, the picture that these trends painted didn't seem to square with the trends I was seeing in the developer doc space. For example. Um, the trends indicated that 76% of people used word or Google docs, that 31% used help offering tools or hats. That 30% used frame maker, that 20% were using a component content management system, 14% using data.

[00:01:21] And I was like, you know. I just am not seeing this in other, uh, tech pubs groups that are creating documentation for developers. And I wondered, you know. How do the trends differ and has anybody ever surveyed just the segment of the population? So I decided to create a survey of my own focusing only on developer documentation.

[00:01:45] That is people who are writing documentation that is intended primarily for developers, engineers, or the sort. I had 50 questions in the survey. It took people about. Nine to 10 minutes to complete. There are mostly multiple choice, although there were a couple of free form, and I promoted this survey on my blog on Twitter and LinkedIn.

[00:02:10] After a couple of months, 406 people completed the entire survey. Actually 855 started 337 dropped out. So this actually range in the number of responses, but 406 made it to the end and hit submit, but the others were still counted as well. It took people nine minutes and the distribution was pretty broad across the world.

[00:02:37] It wasn't just the U S but included a good chunk of people from India, Germany, great Britain, and so on. The results are public and you can go to the site, uh, or go to this link and you can see the results and you're welcome to kind of dive into them. You know, trying to sort through survey results can be pretty challenging, you know, 400 plus responses, so many different factors.

[00:03:03] I'm not an academic trained in kind of survey analysis, but I think when you have 400 responses, it's kind of hard to argue against some trends. So. Let's get into some of these trends. I divided the questions after the survey into five different categories, tools, outputs, processes, API, and just kind of the general profile of the respondents.

[00:03:28] Let's jump into the first section. Tools, because this is the section that I think most people are really curious about. I mean, tools in the developer doc space are hard to navigate. There are a ton of different tools. It's confusing to know which, which to use, especially for your API docs, how you integrate them with your tutorial docs and so on.

[00:03:49] So the first question is, what. Is your primary offering tool for creating documentation. And I had different categories, and the trending category is static site generator tools such as Jekyll, Hugo, Gatsby, Sphinx, um, and you could see some other other trends as well. Uh, but 22% of the people, um, it's pretty, pretty interesting there.

[00:04:11] You can see that. FrameMaker was only at 2.73% so this varies pretty dramatically from those other surveys. I followed up this question with, with a free form question, you know, what specific tool are you are you using rather than these general buckets? And you can see that the number of, of responses, um, a lot of people use confluence, oxygen, XML, flair, Microsoft word, Hugo, Jekyll.

[00:04:41] And I'll get into a little bit of the analysis of trying to sort through this answer, uh, in a bit. Another question. If you write content in a text editor, what editor do you mainly use? Most people use visual studio code or Adam or just notepad plus. Plus. What's the most common source format? Mark down by far, uh, leads the pack with around 30, 37%, uh, followed by HTML.

[00:05:12] And then XML. In general, do you follow a doc says code approach where you treat documentation similar to how developers treat code and overwhelmingly around 56% of the people said yes they do. And this is a huge difference, right? This is a, this is a whole philosophy and methodology that's dramatically different from other tech com spaces.

[00:05:40] What software do you use to create graphics and screenshots and visuals? Most people just use Snagit, but there are a lot of different tools people are using. Um, and you can see a long list here if you dig through the results. What platform do you use to host and publish documentation, especially to provide continuous integration and delivery.

[00:06:02] And most people just use their company's own web servers or infrastructure to publish their documentation. I mean, there are some people using get hub, uh, get lab, but by an, by and large, people are just using the same infrastructure as their company's engineers use. What kind of computer do you use? Do you use a windows 55 54% Mac?

[00:06:24] 40% so pretty evenly split. I mean, uh, I kind of wondered if a lot more people were using Mac, but. Not so much. How do you manage your content? Most people manage their content using get 67%. Right? So this is a really, this is a huge category, right? Because get is is a complex workflow or it can be, it's super flexible.

[00:06:49] It's the same workflow engineers use. And, uh, it's the, the primary way people are managing all their content, different versions, collaboration, uh, kicking off builds and everything. Alright. So now I want to reflect a little bit on how we unpack some of this. Uh, some of these responses about tools. I think they're, they're different tools for different scenarios, right?

[00:07:14] You have. A collaboration scenario where you're trying to collaborate on content with others and develop it. And in those scenarios, maybe use something like Microsoft word. You also have tools that you use for internal content. Maybe you know docs just for internal teams, and maybe you use a tool like confluence.

[00:07:32] Then you have another category, category of tools that you're using to assemble and publish out your content. And maybe you use a static site generator for that, such as Hugo. And then there's another. Category of tools that you're using to edit your content, where you write and edit, and maybe that's visual studio code, and then another tool that you're using to manage your content, you know, push it and collaborate it and store it and so forth.

[00:07:59] Um, that's usually get, and then another. Category of tool that you're using to publish and deploy your content. Maybe your company's own build system. So there's not just one tool that people use. Right. And this is kind of the biggest takeaway is you used to be that kind of people. People in tech comm, you could identify what tool they were using.

[00:08:23] And that tool was an all-in-one sort of publishing, uh, offering, publishing solution, authoring, publishing, collaboration, all packed in one, kinda like a Swiss army knife. But now. There's not just a single tool for authoring review in publishing, you have a lot of different tools that are used for different purposes, and if you want to see some examples, check out this JAMstack site with some links that shows all the different tools people use.

[00:08:49] Uh, and. I also realized that the term tool itself is pretty ambiguous. You know, what is the tool of the editor? Is it the markdown? Is it the static site generator? Is it the build and deployment system? Is it the internal review tools? I mean, if you have six different tools you're using in your author and publishing solution, it's unclear.

[00:09:11] Uh, what response you should provide. When you say, when people ask, what tool do you use? And some people don't seem to be using any tools at all, right? If you're a developer working in the dev doc space and your primary, uh, output is code annotations in the existing code, and you're just using your IDE, such as intelligi a idea to, to.

[00:09:36] Or, or your other, uh, Java IDs and so forth. It's not really apparent, uh, what responses people should say. When you ask them what tool they're using. It's like, no, I'm just writing down as code annotations in my existing editor. I also found that a lot of people. Kind of treat down like a standard, such as data.

[00:10:02] The tools kind of irrelevant because it's used to sort of port the content from one tool or site to another. Um, it's, it's emerging as the standard, uh, that a lot of tools can operate in. I also think that. That one could make a case that the tools influence content. If you look at the history of offering tools in the tech comm space, when people converted to the web, they started creating more, more articles before that, when they're writing big, long PDFs.

[00:10:38] It was more of a book format. When people, um, embraced. Wikis, they sort of, uh, had more feedback loops in the content. Um, when people, when people started writing in data, they had a lot of chunks of content that were kind of small fragments of the whole, when people adopted CCMS is they started. Yeah.

[00:10:59] Taking into account multichannel scenarios. And now with this DOCSIS code approach, I think we're seeing more developer collaboration and input. Um, I have an article that you can read if you want more, uh, kind of exploration of this topic content. Um, how you write influences what you write is kind of a, in my opinion, uh, uh, controversial statement, right?

[00:11:25] Um, you know, if you pick up a pencil, does that differ. That does output of what you create with that differ from what you would create with a keyboard. You know, the same kind of concept. All right, so the emerging picture with tools is that writers primarily are using for internal. Early content development, common tools such as confluence word, Google docs, but then they assemble and build their docs using a static site generator like Hugo Jekyll, Gatsby make docs, and they work in a, in an editor such as visual studio code.

[00:12:00] They publish their content using a DOCSIS code model with get to trigger a continuous integration, continuous deployment model, often deploying on their company's own servers, and there's also a decent amount of wikis, oxygen out, oxygen, XML, and madcap flare use. Let's jump into another section of the survey, right?

[00:12:24] Outputs. I asked, what's the primary output format for your docs? And most people are publishing HTML on the web, but surprisingly 23% are producing PDF. And this ties back to my initial, uh, reasons for doing the survey. I wanted to know, are people really generating PDF? You know, is that just a, a Relic of the old tech comm space now people actually creating PDFs.

[00:12:54] Do you create video tutorials or screencasts? Uh, surprisingly, 28% said yes and only 57% said no. Others are planning to create them soon. So there's a lot of people creating video. You know, I think there's a common misconception that developers hate video. I've had people stand up and be very adamant that we should never be creating video because developers don't want that.

[00:13:20] But that's not the case. Now, if you're not creating video and screencasts, why not? Well, some people just don't have the bandwidth or the tech just changes so constantly that video goes out of date soon or simply because nobody's asked for it. Another question. Do your docs plug into a larger development portal?

[00:13:43] This developer portal, you know, organizes docs for a lot of different products, maybe has a unified search navigation, other features that bring all the docs under one roof and yeah, 56% of the people are pushing their docs into a developer portal. Do you localize your documentation? 73% do not, which is kind of astounding, right?

[00:14:06] If you don't have to. Include localization into your workflow. Uh, it frees up your tool set considerably. You don't have to really think more about XML tools because a localization isn't a requirement.

[00:14:23] Another question about PDFs. Do you usually generate out PDFs and distribute them to your audience? I added another qualifier and 57% said no, but. Yeah, 30% this time said, yes, they usually generate out PDFs and about 9% do create PDFs, but only for internal review. You know, the PDFs thing is interesting because a lot of these tool sets, the static site generators don't, don't generate out PDF.

[00:14:54] By default, a Sphinx is an exception, so by and large just presents more complexity for technical writers if they have to generate out PDFs using docs as code tools. Did you play a significant role in developing and evolving your company's publishing solution? You know, maybe you helped design the site, the workflows, the strategies, and yeah, like 53% of the people said, yes, they're there are building this out.

[00:15:23] And only about 20% said no. Which is interesting because, uh, to build out. A good looking doc site. Using some of these static site generator tools is, is not trivial. It's a requires a UX skillset. So here's the emerging picture. When it comes to outputs, writers are primarily creating. Primarily creating web content that fits into a larger developer portal.

[00:15:48] The writers often help shape and build both the published published publishing solution and the portal and localization video tutorials and PDFs aren't overwhelmingly used, but they do constitute about a quarter of the output. Let's move on to a third category of the survey processes. First question, how do you interact with engineering scrum teams.

[00:16:19] And about 33% are embedded right on the same teams as scrum teams. Another 27% are participants, but in a limited capacity, maybe they're not counted as full fledged members with points and demos and everything. Um, others, about 20% have their own doc scrums. So this is a, a very common sort of pattern to organize tech comm work.

[00:16:47] How do you review your docs prior to release? You know, this, this question ties back to the PDF as well. And this is kind of amazing. 25% said that they use the same code review tools that engineers use to review a software code. So these are, these are your, your code diff tools, the code review tools. Um, and.

[00:17:10] And I tell you this is a huge difference because reviewing documentation in a line by line editor, editor is very different from adding notes in the margins of a PDF or a Google docs type type a document. But about 13% use Google, Google docs or Quip, others use confluence. 12% use PDFs. And so on. Some people, a lot of people, 18% still use in person meeting meetings.

[00:17:42] And this whole, this will, um, connect with a later question about, you know, the biggest challenges people have, and one of them is, is getting engineers to review the content they write. Does your doc publishing, publishing solution have continuous integration and deployment? For example, when you push your content to a certain branch with get do builds kickoff on a server and push the push the docs out to production, and 47% or 48% of your Roundup said yes, they do.

[00:18:16] I, you know, so this is actually a question, just kind of checking. Previous question of 33% said no, but this is a huge kind of shift in terms of how docs are written and published. The ability to just kick off a couple of commands with get and all of a sudden your files are in transit. Being deployed on the server a few minutes later is huge.

[00:18:41] It is huge. If you've ever had to manually kind of transfer and publish files, you know what a pain that is. Do you outsource any documentation to an offshore agency? Uh, no. 93% do not. Right. And this probably speaks to the intellectual property concerns, especially if you're working with APIs and other kind of developer code.

[00:19:05] You probably want to keep that internal to the company. Do you have a style guide for your team that standardizes terminology and conventions about style, grammar and syntax? 77% of the people said, yes, we do. You know, and, and this could be a style guide that you're just adopting from another group.

[00:19:26] Maybe you like the Microsoft manual of style or Google's developer style guide. Uh, but yeah, people aren't just kind of, uh. Going about it freely and choosing whatever styles they want. When you collaborate with engineers, how do the engineers contribute? Well, about 31% actually say the engineers contribute content through poll requests.

[00:19:53] Um, others about the same. Number 31% say the engineers add content to a Wiki or similar platforms such as Quip, and they grab it there. And about 20. 22% say that engineers are direct authors in the version control repository, so engineered pushes their code in get just like a, the other technical writers might be doing this.

[00:20:19] Kind of an interesting, interesting model. I mean, if you look at why people adopt DOCSIS code, it's really to unlock collaboration with engineers and you can see that. The 22% of engineers at least are plugged in directly, and another 30 31% are committing pull requests. So yeah, I mean, if you're in the space and you're trying to get information from engineers, this tool set often allows people to collaborate.

[00:20:48] Here's the emerging picture, right? Writers participate on. Scrum teams, sometimes in a limited capacity, they review docs using the same tools engineers used to review code engineers contribute through through pull requests or through through wikis. The publishing publishing process is streamlined through continuous integration and deployment, and most content is generated within the company rather than outsourced.

[00:21:21] All right, let's move on to the fourth. Category in the survey API APIs, does the documentation you work on usually involve some kind of API and 81% of the people said yes. So I actually really like this question because I often equate developer docs with API docs, and it's true, not all developer docs involve an API, but here you can see that 81% of the time.

[00:21:48] Yeah. If you're working in the dev doc space, it involves some kind of API, so in some ways you can just use these terms, dev docs, API docs somewhat synonymously. What's the most common type of API you work with? Rest API is 56% but native library API such as Java C plus plus, these still constitute a sizable amount with 17%.

[00:22:13] And then a different number of different types of APIs. Uh, trickle-down, like soap API is only around 7% a graph QL it round 7% as well. So it's interesting, like the API landscape is really pretty broad. So how do you know what to focus on? Well, probably rest. And then some native native library API APIs.

[00:22:40] If you're creating rest API docs, do you use the open API specification and 40, 40, a 7% people of the people said yes. Um, 16% said no. Six 15% said sometimes, and other people just aren't working with rest APIs. So this is a pretty strong trend, right? Like if you are. Going to be working with APIs. You should really know the open API spec because that's how a lot of people just document the API.

[00:23:12] How do you render the open API spec into documentation right now? Some of these questions, uh, uh, I would probably unpack them more, but basically the open API spec spec is just a Yammel or Jason format describing your API. And then you choose a different tool to pull that information in and create a interactive, uh, attractive display.

[00:23:34] And the most common one used is swagger UI. Um, swagger usually refers to the tools around open API and there's a free one that's been the standard for a long time. But redox is also heavily used with around eight and a half percent. And a good number of people use internally built tools around 17% of the people.

[00:23:57] Do you primarily create the open API spec manually or do you auto generate it from code annotations? This is a huge debate kind of in the community of people working with open API and it seems to be somewhat split around 22% manually created and 23% auto-generated. And others do both. Who, who generates out the open API spec at your company?

[00:24:21] Primarily the engineers at 36%. The tech writers only generate this out around six and a half percent of the time, uh, but often both work on it. Tech writers and engineers around 20. Hmm. 25% of the time. So, uh, this is another key question now for reference docs like Java, Docker, Doxygen who creates this content, engineers usually create it 32% of the time and tech writers 6% of the time.

[00:24:50] And there's some collaboration between the two 27%. Um, this is kind of interesting because like, as a tech writer, you may wonder, am I responsible for the reference docs of this or is that, is that like an artifact engineer? Should. Provide as part of their development of the code and you would not be out of place to just require engineers to provide the reference docs related to either a rest API or a Java API or C plus plus API.

[00:25:16] I think that's totally within the bounds of what would be common. You know, most, most tech writers typically, uh, are responsible for the tutorials around how to use that content and the engineers might produce the reference. What are the most common programming languages you need to know? Well, a Java script tops the list at around 24% followed by Java at 18% and Python at around 16%.

[00:25:45] This more or less aligns with popularity of programming languages. Which of the following new or trending technologies are you documenting or will you be documenting this year? So there, there wasn't any overwhelming answer. Some of the big, more common ones are machine learning, big data, AI, um, artificial intelligence, data privacy.

[00:26:09] Um, alright, so the emerging picture here is that. Almost invariably, dev docs involves an API, and it's usually a rest API. And when you're documenting the rest API, most people use the open API spec. Both writers and engineers collaborate, uh, as they generate out the docs, uh, using swagger UI or a custom parser.

[00:26:34] And the most important languages to know are Java script. Java. And Python. Finally, this last section just has some profile information about the survey participants or the age range was surprisingly evenly distributed. It wasn't as if most people were young, 2030s or something and everybody else just trickled down.

[00:26:56] Now, there was people all along the spectrum and somewhat even distributions, and the gender split was around even as well. I thought, Oh, maybe. Uh, because programmers tend to be predominantly male, maybe that would reflect in the, the, the tech writers know the four 52% male, 46% female. There were over 200 different companies.

[00:27:19] Uh, I, I didn't tally up to see who was the most, but, uh, we did have a lot of people, uh, from different companies. Um, I think there were like nine from Google and so forth, but it wasn't just like. One company that predominated as far as the college degree, 31% of the people have humanities degrees. 28% have engineering degrees, and 15% specifically have tech comm degrees.

[00:27:44] So this is a good one because a lot of people think, Oh, if you want to, if you want to thrive in API API docs, you need to be a former engineer, or you have to have an engineering degree. It's not the case. We've got 45% of the people with. Either humanities or tech comm degrees that are working in this space, and around 75% of the people are satisfied with their job.

[00:28:06] Uh, this correlates with a satisfaction question that socket Saul asked in his tech comm census. Uh, and he found that about 72% of people are satisfied with their jobs. So it's roughly on par there. The team size. I wanted to know, you know, are most people loan writers that work in huge teams, 34% of, uh, people working in API docs are loan writers and 31% are on small teams of two to four writers.

[00:28:36] And, uh, people who are working with five to seven writers, um, there are 12% of those people. The employee type, almost invariably 86% of the people are full time. And I asked people, what group do you have the most affinity towards? Right? The docs, STC, none. 39% said they feel most affinity towards, right.

[00:29:01] The docs, 14% said STC. A lot of people just don't have affinity towards any groups really. Um, how much time did you spend learning, do you spend learning each day? Just trying to keep up. Around 20% of the people said 30 minutes. 27% of the people said 20 minutes and 14% of people said 60 minutes. So finally, what are the biggest challenges you face in working with developer docs?

[00:29:30] Well that the technical knowhow, understanding the developer technologies to the degree that you need to document is probably one of the big ones that 15% 60% of the responses, but also. Um, just finding time, the bandwidth to create all this needed documentation. Roughly the same. Around 15% of the people said this is a huge challenge.

[00:29:56] Another big challenge was getting reviews. You know, getting adequate reviews. Uh, to get the engineers to reviews stuff is a huge challenge. Around 15% of the people said that. And then another big trend here is trying to write docs that address both novice and advanced users. That's a challenge people run into.

[00:30:16] Alright, so those are the results. And hopefully, you know, as you're making your way in this dev doc space, uh, these results give you some. Validation for maybe the path you're taking, or maybe you realize that you know what we're doing doesn't seem to align with the trends, but I think understanding trends is helpful because you want to kind of choose your, your tool set and your processes and your formats to be generally in line.

[00:30:47] With what's most common in that space. Uh, the, the skill sets people will ask for in job interviews will better match up the expectations of the audience and the engineering teams and working with you will better match up if you're kind of a rogue and doing something completely different. You know, kudos for innovation if, if you're innovating, but also recognize that, uh, uh, you might run into more, um, challenges trying to.

[00:31:15] Uh, cut your own path through through a jungle. So hopefully you can find some of these more well-worn paths. And, and. Uh, find more community, more tools available, more general information about those paths. My name is Tom Johnson. You can find more about, uh, me and, and my blog and API docs on. I'd rather be writing.com and I've also got an extensive API documentation course you can go through for free on the same site.

[00:31:44] And feel free to reach out to me on Twitter at Tom Johnson or through my email address, Tom J O H t@gmail.com. Thanks.