A Technical Communication Conversation — Tom Johnson

This is part of the series of conversations that I originally published in ContentHug, in 2015.

Thank you Tom Johnson.


[CH]: Technical communication has really evolved from merely user manuals to ROI driven approach, UG content, and web based authoring tools. We can say these are all integration points with content strategy, towards the common goal. Considering this convergence, what are the common pain points that technical communicators and content strategists can address by working together? For example if we talk about titles, can there be a role or title for a senior technical writer or a documentation manager that can include overlapped roles and responsibilities of a content strategist too? What can it be?

[TJ]: I’ve never worked with an official content strategist before, but I have worked with various product managers who have played similar roles. When we try to go beyond our own domain of tech comm and include content from other groups, such as Marketing, Product Management, and Support, we’re going to have to negotiate how we share and publish information. Integration of content across departments requires coordination, consistency, and interchangeable information.

All too often, different departments have siloed information that is redundant and inconsistent with each other. It’s really difficult to bridge gaps between the other groups and create an orchestrated, harmonious flow of content that appears as a seamless presentation to the user. The first step is maybe to look for those points of overlap. The second step is to perhaps expand the horizons of our stewardship to look beyond just tech comm content.

[CH]: Assume that you get your dream job or contract, lead or otherwise. What is the most important thing that you have learnt so far that you will put into practice there?

[TJ]: In many ways, I’m already working at my dream job. It’s close to home, involves many challenging programming languages, is small and startup-like, Mac-based, etc. Most importantly, I’ve had the opportunity to implement web-based authoring tools of my own choosing. Having this freedom and flexibility is what makes it ideal.

I think the most important principle in any job, though, is focusing on creating user-centered content that helps the company move forward.

[CH]: There are times when we need to push things around, such as to get a buy in. Can you share some experience when you had to take a really tough call, such as for style guide, for user education, for a new authoring environment, or for deliverables?

[TJ]: Working in an environment that gives the doc team some autonomy and flexibility is key. One area that I’ve had to wrestle with is where and how to publish docs in an authenticated way (without an application GUI doing the authentication). I’ve learned to compromise and do what works. The account management team wanted to publish the content on Salesforce. You have to pick your battles, I guess.

[CH]: How do organizations address the content ownership concerns when we have content strategists, content marketers, technical communicators, and even data scientists? How do you see your role in defining the content ownership process?

[TJ]: I recently had this issue with a product overview document that I was collaborating on with Marketing. I finally decided that marketers have a certain style, tone, and approach in creating content — it isn’t something that you can easily single source to technical documentation (or vice versa).

Another challenge is allowing developers to directly contribute to documentation (pulling readme.txt notes from code repos into docs, for example). Trying to integrate all of this different material into the documentation is particularly challenging when you have multiple authors who write with different styles, points of view, audiences, and more.

[CH]: What role technical communicators can have in disruption–technology or otherwise?

[TJ]: I think technical communicators can move away from their siloed tech comm toolsets and use more disruptive web-based tools. I’ve started down this path by moving from DITA to Markdown and Jekyll. So far, it has been a good decision.

[CH]: Can you name any companies or brands whom you admire for their content?

[TJ]: Well, I think Parse does an amazing job with their documentation. I don’t use their products, but in exploring their site, it’s well-designed, organized, and looks beautiful.

I also think Jekyll’s documentation is well-designed and organized. That’s actually a site I use frequently. There are quite a few places where I’d like more advanced information, though. It highlights how difficult it is to maintain a simple set of docs that appeals to beginners while also providing more in-depth information for advanced users.

[CH]: If you could weave a magic wand only once, what you wish for your current role at work?

[TJ]: I’d like to move away from publishing content on Salesforce and instead publish using Github on Heroku. Since I need authentication, I would publish content into private Github repos that Heroku pulls out. Then I would use Github authentication on Heroku. Other identity access management (IAM) groups would plug into the Github authentication using connectors. Since I’m not an IAM person, setting all of this up is unfamiliar to me. It’s hard to get buy-in for a solution like this when docs are the only product that need this workflow. Marketing usually publishes directly on the web, and engineering code lives happily in internal repos. It’s the doc that needs to be available on the web but behind a secure firewall that only select users can access.

[CH]: Any additional comments that are relevant to this conversation?

[TJ]: I would encourage technical writers to stay passionate and engaged in their careers by writing and sharing information on websites and other venues. Start a blog, write about your experiences. You’ll be amazed what this does for your mind and career.


Vinish Garg | Products. Experience. Stories. I am a EEES (External Eye Experience Specialist) for startups and their goals, for content, UX, and customer experience.