tcworld China 2021 keynote: 'Tech comm and marketing: How to make your tech comm group more visible to those within your company'

by Tom Johnson on Sep 16, 2021
categories: technical-writing • podcasts

• Introduction
• Video
• Audio
• Slides
• Presentation notes
  • The intersection of docs and marketing
  • Post Excerpt
  • The idea of content marketing
  • Engaging users with product stories
  • Example: Independent vs. corporate blogs
  • Corporate newsletters are links to tech resources
  • Docs are at the center of content strategy
  • Same content in different output formats
  • Same content in different deliverables?
  • Single source publishing paradigms
  • Making docs visible to other groups
  • What I’ve learned as a blogger about visibility
  • Building visibility through documentation reports
• Outcomes of regularly sending docs reports
  • Summary
• Concluding thoughts

Introduction

I was invited to fill in and give a keynote presentation at tcworld China 2021 (due to another speaker cancelling the week before). The previous speaker’s topic was on content marketing, so the conference organizer asked if I could present on What is the technical writer’s role in content marketing?

At first, I thought this topic wasn’t something I had anything to say about, especially given that I’d focused so much on API documentation topics over the past several years. But the more I thought about it, the more I realized that I did have a few thoughts and perspectives on the topic. So I decided to embrace this direction and tell the story I’d had inside based on my experiences.

For more conference details, see tcworld China 2021 and my presentation. Here’s a photo from the event:

Video

Here’s the video recording:

I included the Q&A at the end, though due to sound issues, I had a hard time understanding the questions. I should have asked everyone to type the questions in chat instead.

Audio

If you want to listen to audio only, here’s the file:

Slides

Here are my slides:

(I incorporated some tcworld China branding into the slides.)

Presentation notes

Here are my notes on the presentation. I spliced in the relevant images from the slides too.

Tech comm and marketing: How to make your tech comm group more visible within your company

The intersection of docs and marketing

• Asked to speak on a topic in a post I wrote called What is the technical writer’s role in content marketing?

• At first I was like, content marketing isn’t my thing. I’m Mr. API documentation. But then I realized I actually have a lot of thoughts around content marketing, some which might be against the grain, or at least offering a different POV.

• This post I wrote is an interesting one to me because it has a bit of a backstory. At the time (2016), I was thinking of pivoting to content marketing because I felt that it might actually be a better fit for me, given all my blogging. I had started to wonder in my career if perhaps I was in the wrong discipline — why is it I had a tech comm blog but seemed to be somewhat singular in the industry? Why weren’t there more tech comm bloggers?

• I applied for a job with Apigee, with this post as a prime example of how I viewed content marketing and why my background as a tech writer would be a good fit. What’s in that post? It’s the idea that tech docs could help provide the substance in marketing content to build relationships with the audience. Tech writers could leverage their knowledge and docs to create meaningful, relevant marketing content that addresses the user’s pain points and frictions. In short, I argue that documentation can help supply the content for content marketers to connect with a developer audience. Being a tech writer provides a perfect fit for developer content marketing.

• But then ultimately I decided against this career pivot and applied at Amazon instead. During an interview, a senior interviewer at Amazon said he’d read the post and thought that I “got it.” He was sold on me before I even met him, mainly from the ideas presented in that post.

• So although I was trying to spin my background as a tech writer to be a perfect fit for someone who would be creating dev marketing content, in reality, I was hitting on a larger intersection with tech comm and marketing.

Post Excerpt

Here’s a brief excerpt from the post:

“If you’re trying to win over a technical audience, you need to communicate with them on a technical level. You need to understand the technical issues they face and talk with credibility about those issues.

I’m not saying content marketing should consist of verbatim topics from a user manual. But the concepts that you cover in tech docs could certainly be repurposed into larger, more conceptual articles that address strategies around those topics.

For example, a topic in a user guide on “Generating an HMAC Signature for Requests” might be repurposed into an article on using “HMAC Authentication for APIs,” in contrast to other authentication protocols (such as OAuth).

As a technical writer, you have the insight to provide substantial, information rich content that will build relationships with technical audiences.

Marketing writing without substance is going to come across as empty marketing — the kind of brochure or product literature that has such a strong agenda it’s almost unreadable.”

• As tech writers, we’re uniquely suited to creating this kind of content.

The idea of content marketing

• This focus brings me to the idea of content marketing. The idea of content marketing is that you build relationships with users by providing them with valuable, regular content rather than just trying to pitch them marketing material. Documentation seems like great fodder for content marketing material because by definition, documentation is information rich, instructive, and helpful to people. Documentation doesn’t try to sell you anything. Instead, it teaches you something.

• While at Amazon, I had the opportunity to be in a group that was half developermarketing, half tech comm. It seemed like the ideal combination to leverage doc content in marketing efforts, right? As a tech writer, I had insights about features, frictions, challenges, and other details that would allow me to create relevant, engaging content for a corporate blog. And we had a blog!

Engaging users with product stories

• The approach I’ve always tried to follow in my blog posts is to use story as the basic structure. In corporate storytelling, you want to identify the issues that motivate adoption of your product. In other words, you tell the story of your product. In most cases, a product solves a pain point of some kind. That’s the story you want to tell.

• One example from Donna Lichaw’s book on storytelling is with the iPhone. The story is this: You don’t want to carry around multiple devices, what a pain! Now we have this new device, the iPhone, that combines all your essential devices into one (text, talk, and browse the web). Hooray!

• With corporate storytelling in mind, I tried writing some blog posts that engaged with one of the prevalent issues Amazon was facing with Fire TV. Without sharing too many details, the gist of the issue was that developers were submitting apps with inconsistent features, and this was confusing the user experience around those features — some apps had them, others didn’t. Users had to play guessing games about whether an app had the feature or not. This was an important issue to address in developer communication, and I started out by describing the issue before launching into the solution.

• However, my post was redacted to tech tips about how to incorporate the feature, with no mention of the larger inconsistency issue with features in the product. At the end of the article, I wondered why I was duplicating the docs into a blog post. Why not just point to the feature docs instead? The blog post was going to just duplicate everything and go out of date.

• After similar experiences with other posts and topics, where all the conflict was basically removed and it was just a tech tip/tutorial, I lost interest in writing corporate blog posts. Blog posts trended toward release announcements and links to docs or other resources.

• The problem with this reduction is that marketing content loses its appeal. Almost universally, company blogs are PR rooms, not traditional web logs written by real people writing about issues in transparent ways. Marketing blogs are mostly happy path stories. Issues and frictions are minimized. And yet, the universal blueprint for engaging content is story. You can’t have a story without conflict.

• Although some conflicts can help your product’s origin story, the number of opportunities to focus on these kinds of conflicts are few and far between. The mundane rhythm of a tech department addresses many conflicts that aren’t related to a product’s original market pain story. Overall, I found that the corporate space was much too restrictive with this regard, and the content was blah as a result.

• In all reality, documentation is a better place to write content, since documentation is the one domain where you can usually still be brutally honest about a product. Few people read docs in detail, so if you want to address an issue in nitty gritty detail, you can slip it right in. Bury it in the middle of a long topic or in an FAQ — in docs, you can speak plainly and be honest.

Example: Independent vs. corporate blogs

• I’m fairly convinced that you can only create engaging content as an independent blogger. A great example with independent blogs versus corporate blogs happened just recently with the recent device release from Amazon. On the one hand you have AFTV News (Elias Saba), writing about Amazon Fire TV devices. It’s an amazing blog with interesting perspectives and in-depth expertise. Example AFTV post: Comparison of specs for the Fire TV Stick 4K vs the new Fire TV Stick 4K Max — Plus why they matter. It has in-depth analytical, honest review type content and gets 70+ comments.

• Compare the same post topic from the official Amazon group: Introducing the next generation Fire TV Stick 4K Max and Amazon’s first smart TV. The company blog regurgitates product copy and then links to docs (tech specs) as resources.

• Interestingly, Elias Saba went to work for Amazon a couple of years ago, and when he did, he discontinued his blog due to what he considered a conflict of interest. When he left Amazon, he picked his blog back up. (Why he did product management at Amazon instead of corporate device blogging baffles me.)

• Why can’t corporate marketing have the same engagement as an independent blog? Marketers won’t say anything negative about their product; they won’t discuss the warts or engage in real issues. They seem hamstrung with any kind of intelligent, in-depth analysis or cross-product comparisons in the industry. Bottom line: You can’t tell a story if you don’t have any conflict. And if you can’t tell a story, you won’t engage an audience. Even putting aside story elements, the ability to analyze and argue certain points doesn’t come naturally in corporate blogs, and audiences don’t trust the content anyway.

• My conclusion was that if the content was no better than release notes and tech tips, then I was better off keeping that info in docs and focusing on it there.

Corporate newsletters are links to tech resources

• It seems like most examples of corporate newsletters are just conglomerations of updates, new resources, or other product updates. See Stripe’s Developer Digest newsletter as an example (it’s as good as it can be). The inevitable focus of a company’s blog trends toward a “What’s new” type page on a doc portal, just packaged as a newsletter. There could be companies who can do more with blogs beyond announcements and tech tips, but there aren’t many around.

• As a result, if you can’t connect with users around the real issues they are facing in blog posts or other marketing domains, then perhaps docs are a better space to write and engage users. Docs, especially developer docs, seem to have a special license to speak plainly about issues and problems in products. People often think docs have low visibility, but because the content doesn’t exist in the product promotion and release space, you have more flexibility to address actual issues and problems users are having.

• The newsletter can basically provide a list of helpful links to users. Marketers can link to docs for more extended and raw discussion of issues.

Docs are at the center of content strategy

• If you agree that content should largely exist in the documentation itself, that changes the strategy a bit. Instead of pushing docs out to other groups, you can bring other groups to documentation.

• Documentation is unique in that it’s a central tool used by many different groups within the company to do their jobs. A while ago, I was working on a series about tech comm and value in an organization (Value arguments for docs and tech comm). I started thinking about all the different groups that use documentation as tools for their job, and drew this graphic. It had lots of likes on Twitter and resonated with tech writers quite a bit.

• When you consider content strategy, documentation is surely at the center of this strategy. Documentation is the source that gives fuel to so many other groups (Training, Documentation, Support, Marketing, Product Management, Sales, Business Development, and more).

• The basic idea of enterprise content strategy is that you have a single source of content that groups across the enterprise can leverage. Pros of using this content across the enterprise include consistency of message, reduced inefficiency in content development, coordination across groups, and more.

• The opposite of an enterprise content strategy is silos — every group makes their own version of more or less the same content. Cons of siloes are inconsistent content, redundant efforts, confusing messaging to users, etc.

Same content in different output formats

• The traditional idea of enterprise single sourcing looks something like this. You store your content in one system that then generates outputs across all the channels where you need it. This is also the model driving DITA and other content efficiency strategies.

Same content in different deliverables?

• While this model might work in some companies, it doesn’t work so well in others. If you’re trying to generate different deliverables, not just different formats, you run into a host of challenges. Here are a few examples where reuse is challenging:

• Reuse doc intro into product mktg brief. Product briefs might share similarities to product overviews, but the point of view (perhaps third-person) might be entirely different. And the audience might be the decision-makers rather than the integrators.

• Reuse docs for biz dev pitch deck. Business development might find that a slide deck is more useful than a written doc. They’re talking to business execs who prefer to engage more interactively. Docs aren’t nearly as visual as slides.

• Reuse docs for product white papers. A white paper talks generally about a problem and explores different solutions, and indirectly funnels users toward the product as the solution. The approach in white papers isn’t to come out directly with your product description but to describe a problem where the only practical solution is your product. And this solution (your product) only begins to surface near the end. In contrast, docs are much more upfront with product descriptions at the start.

• Reuse docs for interactive video scripts. Training might be a series of interactive video modules that need to be short, conversational, and natural-sounding. You can’t just copy/paste documentation into a video script. Video scripts must actually be listenable as spoken text. Written text and speech are actually quite different.

• Reuse docs for blog posts. A good blog post tends to be more anecdotal and experience-driven. They tell stories and interweave quotes from different perspectives. They start with a recent event hook that propels the topic into relevance. Docs don’t have this same shape.

• Reuse docs for ebooks. Marketers often create ebooks as assets to dangle in front of users to capture their registration details or sign them up for newsletters. Ebooks are actually good candidates for documentation re-use, though the value of duplicating a resource online into an ebook, especially with code samples or other interactive features, is suspect. Ebooks are typically formatted in desktop publishing tools like InDesign and quickly go out of date after publication.

• Reuse docs for KB articles. Knowledge base (KB) systems are typically closed systems with excellent search and related articles tags to surface content. This makes the import of docs into these systems important. However, import is usually one-way, and keeping the articles in sync with docs is tedious. It’s actually better for the KB article to have a few keywords about an issue and then link to the relevant doc for details.

• In sum, you can see that although documentation might be relevant and important to other groups, reusing the content into other deliverables isn’t so straightforward and doesn’t often work.

Single source publishing paradigms

• With single sourcing strategies, the traditional paradigm is to store content in a central repository and then generate outputs for different channels and users. The idea of creating all these separate deliverables that get pushed out to different groups isn’t the only model. In fact, this model seems like a better fit for a print publishing world.

• Another model is to point users to a single source of information. If you have a developer portal where lots of docs live, it might make more sense to just point users to the same page for common information.

• For example, consider some instructions on integrating a code library to enable an API. This topic is likely used in at least two places: a topic on installing the product, and a getting started tutorial. Other topics might reference this step in prerequisites as well. Rather than duplicating the content, just link to the topic. This also keeps the content more minimal. If you reuse the same topic content everywhere, it can balloon the size of your content.

• Admittedly, there are scenarios where the pointer model doesn’t make sense. For example, guides with multiple versions that are published as PDFs. I’m not saying either model is best in all cases, just that the traditional idea of publishing separate outputs that contain reused content is a somewhat older publishing model that seems to derive from the print world more than online publishing. With online publishing, a simple hyperlink can replace the need to reuse content, especially in a documentation portal.

• In short, I’m arguing that docs should be the single source of truth, without attempts to duplicate the content into other deliverables or without the need to even duplicate docs themselves into other doc formats.

Making docs visible to other groups

• If docs are to be this fundamental repository that drives and empowers other groups, then we have to proactively let these other internal groups know about docs. It makes no sense to put so much effort into docs if they remain invisible to all these other groups that could build on and leverage the content.

• Many groups aren’t even aware of where docs are, let alone what they include or what updates have been made. Part of the problem is that tech writers don’t take the time to market what they are writing.

• Most docs have a release notes or what’s new section where they announce changes, but doc groups are usually poor at promoting these updates. Tech writers are really bad about letting others know about new docs, changed docs, and so on.

• For example, if you change release notes or add new info on your What’s New page, how do you let others know? Put aside how you might let actual users know, how do you let internal groups know? Sometimes it’s the internal groups that are interacting with users, so informing the internal groups is the mechanism for getting the message out to the next level.

• Add to this the fact that many tech writers are introverts, totally content/satisfied to stay in the shadows, and this is a recipe for lack of awareness about docs.

• It’s no surprise that tech writers are also frequently marginalized. So many writers complain about being second class citizens, brought in at the last moment, not valued as much, beset with the belief no one reads the docs, etc. why is this so? Because we’re really bad marketers.

What I’ve learned as a blogger about visibility

• I fell into some marketing activities indirectly as a result of blogging. I started blogging because I liked to write, but I quickly realized that having a successful blog requires you to do marketing.

• The basic formula for visibility is this: keep your focus, and then write and promote, write and promote, write and promote. If you write interesting, valuable content (again, keeping your focus on a single domain) and share it with an audience, you build visibility, relationships, and trust with users. I’ve been doing this since 2006, and I’m confident that I’m one of the most visible people in the tech comm field. When I go to conferences, it’s rare that someone who is actively learning and engaged in the field hasn’t come across my site.

• For each post I write, I also share the link on Twitter, Linkedin, and an email newsletter. People often overlook the value of sending email newsletters. When I look at metrics about posts, the email newsletter gets 10x more clicks than posts on Twitter and Linkedin. So I make newsletter signup prominent on my blog and always include it in my promotion strategy. Capturing the email address of your readers is essential. The more people I can build up in my Twitter and Linkedin profiles also increases the potential audience. (This means, however, that my info streams in these channels are noisy.)

• I’ve often wanted to apply these same techniques about marketing and visibility online inside the walls of a company. Couldn’t I be the most well-known, visible tech writer at a company (or at least my docs) using these same techniques? And would that visibility be empowering?

Building visibility through documentation reports

• There’s a super easy method for internal visibility, but few actually do it. The method is this: Create a monthly doc report and send it to all the relevant people. See Sending doc status reports – a tool for visibility and relationship building.

• What does a doc report look like? It has typical sections as these:
  • Purpose and intro
  • About your team
  • Recently published docs
  • Upcoming doc work
  • Support deflection efforts
  • Doc metrics
  • Strategic initiatives
• Beyond the content, you also have some decisions to make:
  • Frequency: monthly
  • Format: email
  • Audience: Look for other reports from engineering groups and use similar groups. No need to ask permission to include them in your distribution.
• Creating monthly doc reports also gives you time for self-reflection about your docs. When else do you look at doc metrics, when do you review tickets and look for trends, when do you listen for partner issues/frictions, when do you report on your doc strategies, and so on? It’s great to do this monthly.

Outcomes of regularly sending docs reports

• What are the outcomes of regularly sending status reports? If you send regular status reports, and the content is insightful and well-presented, you can expect the following to happen:

  • People who you didn’t know previously will suddenly reach out to you.

  • Your manager’s manager will love it and will reply to the report with praise.

  • You’ll become more visible to the people around you, especially if you’re the one sending the report on behalf of your team.

  • People will reach out to ask if certain docs or projects are on your radar.

  • You get better at planning and anticipating long-term doc work and needs.

  • When it comes time to write your annual review, you’ll already have a body of content to draw from.

• Doc reports aren’t a way to single source your content across the enterprise. Instead, it follows a different model that says, here’s the content, now come to it. It’s an approach that consists of better marketing tech docs to the groups that might use it.

• You inform all these other groups in the enterprise about the content they can use. Much more likely that they will link to it or potentially adapt some of it for related efforts.

Summary

• Tech writers might not have much success writing marketing content because marketing strips out conflict.

• If you want to address real issues, you’re better off staying within the documentation domain.

• Documentation is useful to groups across the company, but the difference in deliverable styles and conventions means single sourcing the documentation is unlikely. It’s better to point users to a single instance of the docs.

• For docs to be useful across these groups, you need a strategy for increasing awareness of docs. Sending a monthly doc report helps build the awareness and relationships you need.

• The more awareness you create around docs, the more feedback and input you get for docs. You can leverage this input to make docs even more helpful to these groups. It’s an upward spiral.

Concluding thoughts

Overall, I’m glad for the chance to explore this topic, as it helped refine some of the decisions I made around content marketing and the different paths I’ve taken. I probably hold some views that run contrary to themes in this space. Perhaps if I’d had different experiences, I might have taken a much different argument in this presentation.

In some ways, this was an opportunity for me to unload some frustrations with content marketing, single sourcing, and enterprise content strategy. I’m curious how many others share some of my perspectives, or to hear if they had similar trajectories. I did feel my thoughts were slightly disjointed in the middle here, but the larger trajectory is to imbue documentation as the most valuable asset in a company, the source that informs and empowers so many other groups. Some of that empowerment only comes from being transparent.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.