Hello and welcome to Towards a Smarter World this is an episode with Tom Johnson of “I’d Rather Be Writing”. And this one is a long one, it’s rather technical and it goes deep. So, if that’s not your thing, you might want to skip this episode. But if it is, keep listening to learn about technical documentation, marketing and how to get those content sets interrelated across a very complex landscape.
Cruce
Welcome to
Towards a Smarter World with Cruce Saunders. Today, I am joined by
Tom Johnson, a senior technical writer for Amazon in Sunnyvale, California. Many of our listeners already know Tom as the writer of, “
I'd Rather Be Writing” blog where he posts regularly on technical communication topics and a whole plethora of related conversation. Tom has been in the industry and commenting on the industry for a very long time and it's a privilege and pleasure to connect with Tom, today. Tom, thanks for joining us on,
Towards a Smarter World.
Tom
Thanks for having me.
Cruce
So, Tom, as a well respected voice in technical communications and one that I've followed for a long time, can you tell us a little bit about how you've seen the role of the technical author change over the last 10 years? I know your own career has reflected a lot of change and evolution and certainly, those in technical communications have been keeping up with a lot of variables both technologically and in terms of trends within the industry. What sort of factors do you see impacting the role of techcomms and its evolution?
Tom
This is a great question and I think whenever we talk about trends and factors that influence change in the profession, we have to contextualize it in our region where we are. Because so much is different in Silicon Valley versus the East Coast versus Germany. And all too often on my blog I've just written about things from my perspective and my space and the industry I'm in without adding that context. And I've been called out a number of times by people who say, “Tom, you're in the Silicon Valley bubble, Tom. Where I'm at it's not like that.” So I'm always hesitant to make generalizations.
But from my vantage point and I'm in California in the Bay Area, I've seen a few things that have shaped this industry. One is the API industry has exploded. Like, the number of REST APIs and companies offering their services through an API has exploded and given rise to so many more developer tools. SDK is an API that they incorporate to get the information from those companies.
I think there's been a greater increase in the developer documentation space, the need for documentation for more technical audience people, creating apps that consume those APIs. And as a result, there's been an increased demand for a more technical technical writer as people say.
Also, we've seen this great emergence of the “writethedocs” community which was founded by developer writers (people who were programming and also doing technical writing and decided to call themselves documentarians) because they're suddenly part of this great need to provide documentation for developers.
Now, developer docs isn't new by any means. People have been creating developer documentation for eons but I think there's almost a divide that's creeping up between people who are the more technical technical writer and the less technical writer. In the past they take and tool change, they adopt whether Docs-as-Code or some other system, it really depends on the space they're in.
Cruce
Talking about Docs-as-Code, it's something I've been interested in for a while. There are so many approaches to embedding docs in the coding process which often involve Markdown or some other sort of semi-structured form of content where the development of the code, the development of docs are interpolated in a very tightly coupled way. So we end up with literally needing to parse out that content if we want to use it in any other form other than document assembly.
So, I'm curious about your thoughts on how we can tie together all of that rich valuable content being developed, alongside the development process where it's most valuable. Along with other topics-related content, say product content or support content and help to assemble some of those into
new customer experiences. For example, chatbot customer service or more structured CCMS managed environments that sort of bridge between Docs-as-Code and the traditional
XML based CCMS managed content. I'd love to hear your thoughts on that continuum.
Tom
Yeah, and this is another great topic, really I think that gets to the heart of a lot of what I think you're interested in with the intelligent content focus and the content strategy across the enterprise. But let me backup just a minute and just sort of unpack what I mean by Docs-as-Code. There's the first sense where you actually have documentation inside code files.
For example, a Java Library might have certain annotations with certain formatting in the code that are then rendered out into a Java-Doc file that's the reference for all those classes in that Java-Library. And every programming language has a similar process for doing that.
And that's historically what developer and API documentation has been. REST APIs don't follow that model. They don't necessarily have to be generated out from the code itself much more open although you could generate from the code if you want. But Docs-as-Code is also used to refer more generally to treating documentation with the same processes that you treat code with, doesn't necessarily mean that you have to have your docs inside of your code files.
In general, if you for example have your content in a text file format; something that's readable in plain text, it’s not Microsoft Word file or FrameMaker file that's only readable within a certain editor. So, you have a plain text file format. You're managing the content with version control such as Git or GitHub or whatever.You’re building your output from the server. A lot of times you compile your documentation project, build your documentation project on your own machine.
But or anything. It's all just kind of executed. They call that continuous integration, continuous deployment.
A lot of times people use static site generators for this these are basically applications that package up all of your Markdown files or whatever lightweight format you have restructured text, put it into templates, and build out your website, just packages that it can run logic.
A lot of times I have scripting logic like Liquid or other languages that offer advanced functionality.
Anyway, my point here is that a lot of times And the paradigm is much, much more common in the developer documentation space because a lot of times in the developer documentation space you have developers writing the documentation. So, they're naturally going to use the tools that are familiar to them, the processes that are familiar to them.
And if you're collaborating closely with developers or you just want to piggyback on their same infrastructure harmonized with their same methods, then it's a great fit.
Like, say you have a chatbot or you want to reuse it in marketing content or you want to generate out PDF or do other channels and you can reuse the content in some ways. We generate out PDFs from our Markdown, we use Prince, this is like an
XML. I don't really know why it's called Prince
XML but it converts your HTML into a PDF using CSS. So it's a little bit of a pain to set up and configure but so are other PDF transform techniques.
You can also do things that are quite sophisticated: You can store your content in another format such as YAML. You can write little scripts to loop through your data source in YAML and push it out into myriad templates which is quite robust and gives you a lot more flexibility than maybe is possible in other approaches. Then, you could put it in any format you want. You could write your content in JSON and render it out into the templates you want for whatever chatbot schema you're writing for or whatever other approach you have.
The limitation really is that there's no real universal standard, like DITA provides. DITA is supposed to be a standard schema that a lot of tools can understand. Whereas in the Docs-as-Code space when you start implementing this advanced logic, you end up with custom programming code to render it. That doesn't necessarily migrate well if you want to change your system from Jekyll to Hugo, for example.
You have to figure out whatever loops or other scripts you've got going on which would be coded in Liquid, how those would work in Hugo's templating language would go and so forth.
So in some ways, like programming languages themselves, if somebody writes a program in C++ and you want to convert it to Java, it's like you've got some work to do. There's not a universal programming language, so you pick what toolset you like and you work within there, and there are tradeoffs.
Cruce
I'd love to run a scenario by you, related to the supply chain that you've described within a traditional code development lifecycle, that may be managed in Git where we have whether it's Markdown or some other ASCII text that is in a version-controlled file. And yet, where we're needing to transform and use that content in different ways downstream.
So, you've talked about YAML transformations and other ways to do that with code. I'm wondering if some of that might be exportable into, for example, a more structured form mapped directly to schemas that would be essentially XML-based which would allow us to move that content into a CCMS and then enact other downstream processes on it, for example, semantic enrichment of that content. Because of course, when we're in Ascii-based environments.
It is possible to add semantics and I know a lot of organizations actually do in Markdown, do some form of semantic annotation with a proprietary format; inside of a traditional Markdown structure. But if we wanted to apply more advanced semantic annotation or other structural usages inside of a CCMS or another content lifecycle technology that can be used by more non-technical contributors, is that path clear? What are the obstacles to that path? And is it possible ever to round trip the content associated with such a workflow?
Tom
That's another great question. I was actually meeting with a group just a few weeks ago, they were describing their process and it's really relevant here. Basically, they were using Adobe Experience Manager but they weren't authoring natively within it. They weren't going into the AEM, UI user interface, and writing their content in DITA or XML, and using the tool in a straightforward way like that.
Instead, they were starting with GitHub, keeping their content in Markdown and then they transformed it into Lightweight DITA or maybe it was transformed first to HTML and then to Lightweight DITA . Anyway, they moved it into Lightweight DITA so that it would conform to a DITA schema so that it could be then consumed by AEM, because AEM would record at least their doc add-on requires the
DITA schema or a
DITA XML format for the content.
So then, they used AEM mainly as a publishing engine and they would integrate their content with the rest of their content, their marketing content and so forth through this process. But their origin point was not in
DITA XML. It was in Markdown on GitHub and they chose that because they had a lot better collaboration with engineers, they were able to, I mean GitHub has some great tools for managing pull requests, seeing what people are changing, merging, editing across different branches and so forth and deciding what you're going to pull in and what time.
They’re just superior in so many ways, the whole power of Git and some of these platforms, like GitHub that make the pull request workflow visible.
So they wanted to harness all of that but also get the benefits of a system and I find this interesting because the Docs-as-Code models tend to work better in smaller implementations. At some point, you need a larger system to do more robust things even just search.
At some point, you're going to have to either buy a third-party search service like Algoliaor or Swiftype or ingest it into some larger search process because Lunr search or whatever is not going to cut it beyond a certain point. And all of these systems have the same problems they get to a certain point and then I feel like you need a larger system to do more, even just tracking metadata.
I want to know who authored the topic and when it was last authored. I want to add taxonomy attributes about just tagging so that it fits within my enterprise taxonomy and can be surfaced in certain places or leveraged. You hit a point you can’t really do that.
A lot of big companies, like Microsoft, who have really been incredible innovators in this Docs-as-Code space, they basically just threw away their old XML system and replaced it with a Docs-as-Code model and it's amazing to see how they did it. But what's very clear is that there's a tremendous amount of custom engineering that's powering this, even if it's run on GitHub and people are using Markdown there's a lot of scripting going on.
In order to achieve some of this higher level stuff that I'm saying is only available in systems, people resort to custom engineering and that's fine. It allows you to right-size and do exactly what you want for your needed workflow and not be stuffed into some stiff system. But it also puts you at the mercy of an engineering team for what you need and if you don't have an engineering group or if your engineering group doesn't have the resources and talent to do some of this scripting with your content, then you might run into some challenges.
But it's a tough problem how you scale at a certain point in terms of implementing this enterprise-wide content strategy with Docs-as-Code. For the most part, Docs-as-Code is most common in developer shops for developer docs which don't tend to have as complex needs as other groups, like PDF and translation and other reuse is not typically as common of a need. I'm not saying it doesn't exist, I'm just saying it's not as common.
Cruce
Beautifully logically thought through. I have also been impressed at the different forms that enterprises have been taking into addressing these issues with manual transformation kinds of scripting and hacking together point to point systems. I am concerned that it's not holistic and sustainable in a way that would allow many departments to contribute to integrated customer experiences.
That's so the taxonomies of that content or the terminology used within that content.
And so, the orchestration of content among systems and among silos is definitely the way of the future. We have to get there because of this need for docs to participate in the marketing lifecycle, for example, or vice versa, marketing content to appear within documentation experiences from the standpoint of providing up-sell and resell and solution set to what is initially a documentation or support kind of inquiry.
Because the answer might be to take a look at these other parts of our product suite. The thing you're trying to do can't be done in this product but it can be done in new products. And therefore, let me connect you back to our marketing loop. And certainly, in an organization like Amazon that has to happen all the time. But I think that's true, really, in any software company and a lot of product companies and increasingly everybody.
The customer gets to move around from different content types to different content types. API docs not necessarily but maybe, but we've got to find ways to integrate so that analogy or that case study that you were relating is very much in-line with the architectures that we are moving towards with enterprises, towards decoupled content sets that are structurally aligned. So they share some sort of schema standard that is managed by the organization and or semantically coherent.
So the semantic tags are meaningful from department to department. But in order to do that we've got to get the content out of code in a way, or out of other forms of static confinement. So I think you've painted a picture towards that. I'd just offer space for you to reflect on words to the wise for anybody contemplating this same set of challenges.
Tom
Well, I definitely think you've hit upon one of the biggest issues and challenges because I just see a lot of fragmentation. People need docs so they hire a technical writer in their group. I'm talking about large companies that have umpteen departments that don't even connect with each other. They need docs. They hire a technical writer. The writer uses whatever tool to create docs and then the same thing happens in another group and so forth. You’ve got all these little tribes of people and they each have these independent writers and maybe have different formats.
But from the customer's point of view, If they look at one set of docs and see that it looks like the person uses Microsoft Word and they've got their own style going and another person has a totally different approach. It just seems like a lot of inefficiency and waste.
And I certainly have a lot to learn to try to figure out how to overcome these silos and tribes and different approaches. But I think you're onto something with
I was listening to some of your
other podcasts about, having champions at the C-level for content, the chief content officer role and so forth. The person that's pulling all this content together which is sort of foreign territory for me. I usually am just embedded within one group that doesn't have larger concerns like that but I think it's a worthy goal and ambition.
Cruce
A lot of organizations have started lumping content initiatives at a level of something called “customer experience” or “product” or “product experience” where sometimes the in-product content, the docs' content, support content ultimately roll up to one accountable executive. And that's useful because at least there's somebody accountable for all of that. We just had a recent conversation with somebody who is the head of omnichannel at an organization and that was being given broad purview above the product teams.
So in terms of org structure, there was stronger than a dotted-line to somebody responsible for developing customer experience across channels. That's interesting.
It's rare at this point, and it's very rare for C-level folks to be involved. But we have had in the last year CIO-, CMO-level sponsorship because I think this conversation is starting to make sense in real dollars and cents terms, beyond the academic “wouldn't it be nice if our content worked together” level of the conversation.
And more into the like we cannot deliver this next generation of customer experiences that everybody is talking about, these personalized real-time assemblies without some kind of coherence in our content sets, without some kind of unified process, without some kind of
unified taxonomy and structure.
So we're not there yet, but it seems like it's moving in that direction. So I agree it's aspirational but I can report back from the field that it does appear that motion is underway.
Tom
I think one reason that maybe companies are hesitant to move in that direction is because there is this desire to
stay nimble and fast and agile and to keep teams small like spin-off an engineering team, having to go chase down some disruptive innovative idea, give them five to 10 engineers and one marketer or two marketers and maybe a tech writer and see what they do and give them full autonomy to make decisions from beginning to end. So that they can kick out some idea, rather than going through some larger, slower process that involves getting multiple organizations on board and aligning with different teams and standards.
I think this is common in tech in general just to have these little tiny startups inside big companies to see if they're going to take off. Because a lot of times products flop, other times they're successful. I don't think organizations want to invest a ton of money in something if it can't show some initial signs of success. But again, that's totally not my area of expertise.
It's just some random sort of observations about small teams versus large teams and what you can accomplish. Because certainly finding the content just that you're looking for, or almost automatically surfacing content and faceted filters that are aligned with enterprise-wide
taxonomy and so forth. That's not going to happen with a small team with one doc writer who doesn't even have a style guide and choosing his or her own toolset at random.
Cruce
Well, I think of an organization like Amazon on the code side and how successful Amazon has been at building service-oriented architectures internally, and some of those teams are small and they all have a startup mentality from the little I've observed. But it seems like they're all based on some sort of standard. So it's like okay, do what you want, but there is a style guide or there are some coding guidelines or there is a structural schema to conform to.
It doesn't mean everything has to go through a governing body. You’re right, that is the number one objection we get when we start introducing the idea of internal standards. We just need to ship something. But if Amazon had that approach, it would never be an integrated customer experience juggernaut. It’s like there's some standard by which those teams agree to innovate.
Tom
Well, definitely different organizations are more on those tiers than others, like the AWS organization. Definitely, they're working really well, they've got solid doc processes and editors and workflows. They're like the example of how to do docs right. I'm not in that group, I’m in a different group, I’m more in the app store group, just have a couple of other writers tackling a large variety of projects.
But in terms of what is the central coherence, I wouldn't want to try to venture out there. But there is a principle at Amazon about customer obsession and working backwards from the customer which user-centered authoring, user-centered design, user-centered documentation is nothing new, but that is a guiding principle that we try to align with. And you can see just in the way the products have developed that principle in place and my hope is that one day it will trickle down into the docs.
I would love for Amazon's doc brand to be customer-obsessed documentation like you open it, you start reading it, and you're like, “Oh, yeah I can tell they’re totally obsessed about customers here.” But I think we all have a lot to learn about how to accomplish that. It's very difficult. It's one thing to have products that people feel that people can love the product brand and so forth. But documentation is in another category, it's like the tax code. Who loves reading tax-code instructions? If you can even get people marginally satisfied, then I think that's a win.
Cruce
Fair. Well, on that front for techcomm professionals, there is so much that people must master and manage to keep up with all of this. And I think you happen to be uncommonly gifted. I think there is also this perception that I can't be Tom Johnson. Like how do tech comms professionals grow, evolve and stay sane?
Tom
I’ve been thinking about this a lot because I definitely feel this is the biggest issue in techcomm. How do you keep up with all this technology? And this past year, I've explored themes about: well, should you be a specialist, should you be a generalist, and how do you navigate those waters? The reality is that companies want you to be both. They want you to have specialized technical knowledge. They want you to have really good writing abilities. Basically, they're looking for people often say a purple squirrel or unicorn but I like to be more specific.
They're looking for a Hemingway-Turing hybrid kind like Ernest Hemingway in the evening and Alan Turing. Like the half programmer, half writer kind of individual. How do you possibly do that? Like, how do you document a C++, SDK in the morning and the next day you're documenting node JS-code? The next day you're documenting
XML schemas and the next day you're explaining Android processes. Like, who has the bandwidth to be familiar and competent in half a dozen languages and to write at the level that advanced developers need?
In order to survive as a “technical-technical” writer, you have to carve out little chunks of your workday to just consuming and learning technical material through different learning resources online whether Safari Books Online or Udemy courses, books, tutorials. I think it has to be part of the workflow because otherwise your skills dull and the very worst that can possibly happen to you in the developer documentation space is to feel that you're not technical. Because no matter how good your writing skills are you could be an amazing writer and a strategic thinker, but if you're not technical, you've just lost all credibility and nobody's going to hire you. Depends on the job, right? Maybe you're hiring, you're shooting for a manager role or something.
But this sense of how do you stay technical, just so that you can write well. Like, let's put aside the fact that somebody may be a great writer. But if they don't have the knowledge they need how they are possibly going to even write? Their skills are going to be dormant. So even if you just wanted to focus on the writing, you wouldn't be able to do it without that technical foundation.
So anyway, I think that people need to carve out an hour to two hours a day, peppered through their workday and at home just learning what they need to know to thrive and be successful. I think as you do that more and more your brain starts to become more plastic and you get into this learning mode and things just start clicking a little faster and hopefully it's not so painful but becomes enjoyable. I realized this the other day. I was like, “You know what? When I learn something and I dig into this it sort of energizes me. I like it, it makes it a lot more interesting.”
The developer landscape is so full of opportunities to learn, granted, it’s technical learning but it’s a huge mountain, forest of technical concepts and languages and frameworks to play around with and explore and that can be energizing.
Cruce
I started out in the web marketing world and when I first discovered technical communication which was actually in 1999. Somebody asked me to do a talk, an STC chapter about, “What is the internet? And how will it be used for publishing in 1999?” But it was amazing to me the renaissance thinking that was happening and that was very inspirational to me.
There was this whole part of the world where people were interested in technology deeply and interested in communicating about technology and so they were both really quite literate and word-oriented communicators coupled with technologists who were very quantitative. So like you said, it's something like Ernest Hemingway and Alan Turing, that learner dimension you added is beautiful, like constantly learning renaissance people.
I think organizations need that kind of thinking in more places. In some areas, the organization is pretty easy to get myopic. But it seems like in techcomms there is this constant need to learn, keep nimble, and constantly apply what's being learned in a form that could be expressed as teaching. So it seems like technical communicators are learners and teachers and I love your way of illustrating that whole landscape.
Tom
But I've seen people, different groups who are trying to hire technical writers in developer doc roles, they become very fixated on oh, this person really needs to know Java or we need somebody who's really in the depths of C++. And they spend months looking for this candidate and never find somebody and eventually settle on somebody who partly fills the requirements.
I never quite understand why they don't just take somebody who's like an avid learner and a good writer and put them through one of these boot camps; a technical boot camp. You can find Nanodegrees on anything and in a month or two you can have somebody ramped up on a technical language to the degree that they would need to document something. I don't quite understand why companies don't get that.
But yeah, a lot of companies do have engineering excellence divisions that have lots of training and so forth, but there seems to be this mindset. I think it's from engineers that either you’re technical or you're not and if you can't articulate this function, tell me exactly what's going on then you're not worth pursuing.
And it's just such a sad thing to see and to see interview processes lag, and a good candidate who would otherwise probably excel just be passed over for their lack of technical expertise even though their writing experience is accrued over many years and has layers and layers of sophistication.
Cruce
That triggered the thought that hiring managers should also consider that going through the process you describe of training somebody in a technology and then having them then teach that in the form of documentation or writing is an advantage. In that, you've got somebody who's newly learned the concepts of teaching somebody who is newly learning the concepts. Do you know what I mean?
Tom
Yeah. In fact, the way I got my first developer doc job when I moved to this area was by taking detailed notes on a JavaScript course that I had watched on lynda.com. I went through this course and I took detailed notes and explained it. Here's how you do X, Y, and Z in this language and it was like 40-pages and I presented it to them because they were like on the fence about me. They were like, “We really wanted a candidate who had a stronger JavaScript background”. I'm like “check this out.” And they're like, “All right, we'll take a chance on you”. And I did a great job in that role.
I mean, it was perfect because you only needed one language and JavaScript is very entry-level because you can run it all on the browser. But if you just go through some course and teach it and articulate it through writing. I think that's a great way to kind of demonstrate knowledge as well as retain it yourself.
Cruce
So you've written a lot about quality and documentation but it just comes down to this simple question: how do we know if our docs are good? So
Tom
This is another great question. There are a couple of different paths you can go and one is a lot easier than the other. But I'll explain what we've tried, we've tried putting feedback buttons on the page and people are landing on the page and they can't figure it out and they click feedback and we get their response. That's one indicator. Problem is, it's so random you don't really know who the person is, whether they're your target audience, what company or what they're trying to do.
Are they an important person that you're trying to reach? Or are they actually developing like a significant app? Or are they somebody who is just learning a platform on a whim as a hobby? So it's really hard to try to define metrics around feedback responses. Additionally, it's hard because people usually only have feedback when they have complaints, so then it's skewed already.
I have come to the thinking, to the thought or whatever, I have come around to this idea that to get good documentation, you have to push it through five stages of a review before you release it in order to ensure that it's good. And if you push it through those five levels of review then you can feel confident that it's good enough.
The first level of review is to test it yourself. Like can you make all the instructions work on your own? Which sounds like, of course, that should be a given. But let's say, you've got some sample code that's meant to be incorporated into an Android app. You might have to actually get a sample app to test it, make sure you can do the instructions or your team. The second level would be to review the content with the product team, the engineers who coded it, the QA, the PM, and so forth.
If they vet it and they say, “Yes, this is correct and clear and you've addressed everything.” The next level would be to widen the stakeholder. So maybe you've got field engineers and support groups and other people who might be interested, but they're not as part of the product team. For us, it's mostly the field engineers. So they look through it and they review it.
After that, we run things through our legal department, which legal only really look for certain red flags and so forth. They're not really going to help you make the docs great or anything. They're just part of the review. And then often we have an early release partner, so people who get stuff ahead of time and we'll get feedback from them. But after those five levels, if you publish the documentation you should feel that it's good. If by that point, the docs miss the mark then something is really wrong. Like, maybe the product is just bad or the processes for doing it are just poorly designed.
I know that there is a strong mentality, especially in Agile, of just pushing something out there and iterating on it based on feedback and so forth, but that doesn't work so well in docs.
And you can get all those people, the PMs, and the engineers to review docs when they're actively working on the product and moving towards a release.
So putting a lot of the review processes prerelease rather than post-release tends to be more successful in just ensuring quality with the documentation.
Cruce
Nice. This whole quality conversation is addressed as well in academic circles. And that academic-practitioner interaction in tech-docs is an interesting one. I know you've spent some time focused on the academic-practitioner conversations project. Can you talk about how that came about? How can listeners get involved in that conversation?
Tom
Well, this is a project that sort of fizzled. This academic-practitioner bridge and collaboration. I love the critical thinking that takes place in academic writing. I mean, buried below all the conventions that they're kind of forced into there are some really deep thinkers that are admirable. And if you're writing blog posts great foundational material to just get your wheels turning and to have evidence for things that's really been vetted and so forth.
The sad thing is that academics are trapped in an institution that is driving them into oblivion. They have to write in thick academic discourse. They have to publish in journals that most people can't access. The timelines are incredibly long, six-months to a year for an article to be published. The review process can be brutal and after all this work, they don't really end up reaching the audience for which the research was originally intended.
You don't have technical writers and others in the field who are just hungry for the latest academic journal. Now, of course, the ideas often find their way out to the field one way or another. But academics, they're sort of trapped into this 10-year rat race and it forces them to follow a path that isn't necessarily going to connect with field practitioners. There is not always a strong emphasis on the technical foundations that a lot of students are trying to ramp up on in order to become marketable. So that again is another blow.
Despite all this, I still find a lot of value in articles and I think it gives me a lot of things to think about which are essential for writing. So my initial idea with this project was to have academics write guest posts, other FAQ type posts, get their voice and their research out in a format, in a medium that's more visible and consumable.
And I sort of let the ball drop, but also I just didn't get very good responses on that. Like the analytics and traffic and so forth were really low whenever I would bring this topic up. There is interest in the research itself but not necessarily presented as, oh, here's the latest from academics or something. It's like, oh, we have research about this. And oh, by the way, it's in an academic journal, but I'm summarizing it here. People are still fascinated by that.
Cruce
So there are so many forms of lock-in for valuable content. And I’m realizing this is a conversation that is happening as we’re recording on Twitter, with regards to a bunch of different content strategists talking about various forms of lock-in. And one that hasn't come up I think you've described perfectly which is locked into academic publishing lifecycles, where there's some really valuable and vetted research-based knowledge being generated but it’s not being able to get into practical use in really the most efficient way.
So that's something as a society we’ll need to confront in order to be able to continue getting smarter. It seems like in artificial intelligence and other fast-moving
fields, they've shortened the cycles on a lot of that and there are some better practices. But in many other
fields of academic publishing, certainly including technical communications, there is a large gap that you're describing.
Tom
Yeah. And I don't mean to sound so negative there. But it really is the case, I think, that they are locked into that sort of publishing lifecycle and they have this tenure pressed against them and if they want to thrive as an academic they have to publish in those journals. But it’s like those journals aren't really connecting with the audience. I don’t know. I'm kind of curious to know what the long term viability of a lot of programs is.
I think attendance in a lot of these programs is actually up like they're thriving as programs. But at the same time, sometimes students midway through, start to realize that there is this incredible technical need they have to just have a stronger technical foundation. And some of them start to get a little bit nervous about that.
I had a friend who partway through, he said, “I realize I should have just gone to one of these boot camps instead of a master's program”. Another student reached out to me and said, “I kept reading information about API docs on your blog. And I was like, they didn't say anything about API docs in my course and so I wanted to find out more about it.” Well, it's interesting to see how this plays out. But we need these programs, we need teachers to imbue the next generation of writers with best practices and good principles.
So, I hope it works out and maybe these publishing houses will open the doors. We've already seen some do this, open the doors to the publications. The main thing is that they have to incentivize professors outside of tenure with some kind of motivation to publish, inform and interact in ways that connect with technical writers. If you're a professor and you read a blog post, the tenure committee could care less. Or if you record a podcast they could care less. If you even work on a project as a contractor, they could care less. What they care about is whether you publish the super triple-blind vetted academic writing.
Cruce
Indeed, you're educating the next generation of techcomms professionals in many ways. I personally can't believe the amount you write. I am inspired by it because you're able to really cover a lot of territory and you're really generous with helping others in the industry to pull themselves up. You have a free course about documenting APIs which looks excellent. Maybe you can talk a little bit about the key topics for that, what prompted you to create it, and then we'll transition to a final big picture question here.
Tom
Okay. I started creating this
API documentation course when I was asked to give some workshops on API doc and this material just grew and grew. Of all the workshops, I shouldn't say of all the workshops, the main workshops I've given have been around API documentation.
In fact, I can't even remember any other workshops outside of this topic. But they're very popular because they feel like they address a gap in the field where you have a technical writer trying to become a “technical-technical” writer or just an API technical writer. This bridge from the end-user doc space to the developer doc space. How do you make that transition? Well, this course is designed for that. It's focused on REST APIs which are the easiest thing to document in the developer doc space.
You don't necessarily have to have a programming background. You just have to figure out how you initiate requests and responses and look at the JSON and document it. It’s not necessarily hard to figure out but there's certainly a pattern and a structure to follow. There are some standards, one called “The Open API specification”. There are some tools that allow you to do the requests and responses as well as generate out interactive docs that have little try it out buttons with swagger and so forth. A lot of people just it's new territory for them. So yeah, I just have been building on this as a course and developing it and it's a lot of fun.
Cruce
I'm inspired in that area in particular because I feel like APIs are the future. They have certainly been, in the near-past, driving all of the transformation in the software industry in many respects. But I believe it will be the future of knowledge to move via APIs. And certainly, every other form of interoperability between the thousands of SAAS-based applications out there all depends on good API documentation.
And ultimately, I imagine a world in which some of the APIs learn to talk to each other through machine-based doc scouring which will be another horizon for us to encounter where machines can learn to talk to each other, back and forth rather than developers have to mediate every interaction between APIs.
But this ability for technical communicators to wire up the world through API documentation is pretty cool. And on behalf of the community, thank you for contributing so much to helping educate people in the space.
Tom
Hey, thanks. Yeah, I like this idea that you're throwing out about machines just consuming the documentation and I think you're right. It's definitely So yeah, I totally see that potential.
Cruce
Cool. Well, as the last big picture question, Tom, I'd love to just ask you about significant changes ahead in the next decade for us as both creators and consumers of content broadly.
Tom
Well, I would recommend first check out a podcast from Ellis Pratt. He recently addressed this as a warm-up to his keynote at an upcoming conference. But he talks about there is still a need, there is a strong need for writing skills. If you listen to my other trends presentations, “The Takeaway”, that often I communicate is that this direction we're heading towards of the technical writer requires all this focus on the technology and I've marginalized the writing.
But that couldn't be less true from what I really believe inside, in my blog, “I'd rather be writing”, definitely suggests that I place a high value in the writing and I don't know how to really communicate it. But some of the more complex documentation tasks can only be tackled with really deep analytical and writing skills. I definitely don't want to marginalize that.
But the story for the next 10 years is the story we've really had in the last two decades. It's this combination of technical and writing together in a way that is harmonious and cohesive is really powerful. The more technical you are and the more writing ability you have and the way, your ability to bring those two worlds together and become that Ernest Hemingway — Alan Turing hybrid is really what's going to make you successful.
The ability to just learn different technologies. It could be these core programming languages one day, and the next day you're looking at neural networks or blockchain and Rust programming language. I don't know, all this stuff that the fringe technology that is becoming mainstream and so forth. The ability to learn that, that's got to be key.
I mean the pace at which things are happening requires us to be better at learning.
I've met so many technical writers that I look at and I know we all say, “Oh, yes, we're always learning and it's always good.” Then I ask him, ”What are you learning?” And it's like, ”What do you mean?” It's like, “No, are you actually learning something right now? Are you learning some new technology?”
It's often not the case, but our field is moving so quickly that unless you can figure out how to learn quickly then you're going to be left behind. I actually just bought a new or not a new, a 2016 Honda Odyssey after our 2003 Honda Odyssey gave up the ghost or at least was in junk repair status. I was excited because this 2016 Honda Odyssey had a new built-in navigation system. I could connect my phone with Bluetooth to it and as I started to use this built-in navigation system within the first five minutes it became clear that I would not be using it.
It was just like old technology. I mean, to enter a direction I had to use a little round dial and navigate an alphabet. Turn the dial until I hit the right letter and then press it in to select it and then turn the dial to the next letter. I'm like, “You've got to be kidding me.” Why did they put this ancient technology into vehicles, in a way that locks it in? Like why not just put a blank little computer there, that they can keep updating just like our smartphones now?
It's sad because now I have this LCD panel that basically does very little in terms of navigation. And I'll just be using my Android phone there instead. But I relate this to say that in five years technology just moves along so quickly that all this other stuff just gets left behind and we're kind of like the car. If our technology is the five-year-old navigation controls and we can't really grab the latest mapping apps on smartphones, then we're not going to be used and not going to be leveraged.
So we have to learn to keep pace with things and to incorporate that learning so that we can actually leverage our writing skills. When we have it in our minds what to say and how to communicate it because this knowledge is flowing through our veins. So, that's what I would recommend is just to incorporate learning more regularly into your day, just to empower you in the field and to empower you to write.
Cruce
Knowledge is coursing through our veins. I love it. And Tom, thank you so much. Where can our listeners follow-up with your work more closely?
Tom
You can check out my blog at, https://idratherbewriting.com/. I'm also on Twitter, @tomjohnson and I'm on GitHub, @tomjoht but probably not gonna be most fruitful there, you just see my commits to my blog and other work projects, and that's about it.
Cruce
Awesome! You know when somebody gives you their GitHub credentials, that they are in the code.
Tom
Okay. Sorry, I actually have to add one more thing. Last month, I lost my work ID and somebody reached out to me on LinkedIn and they said, “Hey, I found your work ID.” And I was like, “Huh. How did they find it?” And they’re like, “I just googled your alias which happens to be my GitHub alias, too.” And they're like, “I found you through GitHub.” And I was like, “Dude, this is so Silicon Valley-esque”. To have somebody locate me through GitHub on a Google query on my lost ID.
Cruce
Anyway, content discovery as code, I love it. Thanks very much, Tom. I really enjoyed the conversation. I hope to be able to continue it in some asynchronous form through the years as the evolution of content and customer experience continues.
Tom
All right. Thanks, Cruce. I appreciate you having me and I really like your podcast. I have been listening to some more episodes, you've got some amazing content and really knowledgeable people on here. So thanks again for providing this.
Cruce
Awesome. See you.