Technical documentation is arguably at the very heart of every successful business. Unfortunately, it’s an area that’s often overlooked and misunderstood. Here to share with us its importance is the Principal Technical Content Developer at Qumulo, Michael Khmelnitsky.
Michael joins Christopher Willis to shed light on why documentation is the beating heart of the company and how you can better develop it to help customers understand your products and business. Michael then lets us in on how he’s building a consolidated content portal, the difference between usability and usefulness, and where marketing communicates differently from technical documentation.
This conversation has so many nuggets on creating various content for your organization, ones that drive impact, growth, and success. So don’t miss out!
Watch the episode here
Listen to the podcast here
Read full episode transcript
In this episode, we have Michael Khmelnitsky. He’s a self-professed content fixer and Principal Technical Content Developer at a company called Qumulo.
Over the course of the interview, we’re going to learn about building a consolidated content portal from scratch, hear about how content is a pathway to the beating heart of the business, and how usability isn’t the same as usefulness when it comes to technical documentation.
Let’s sit back and get some insight from the flock.
Michael, welcome to the show.
Thank you for having me, Chris.
I’m very excited to talk to you. I know that in your role as Principal Technical Content Developer at Qumulo, you deal with the challenges of creating both content and owning a portal. I’d really be interested in kicking this off by understanding some of the unique challenges that face you in your everyday life with the creation of technical documentation.
As you go along and grow your career, it becomes a matter of scale. You grow, and the problems also grow in scale. A lot of these challenges have to do with explaining what it is that you’re trying to build to the stakeholders and almost selling the idea because the building itself is the easy part. Like in many other companies where I was brought in as the fixer for certain things, the challenge was to first of all identify what was already there and where that content could go because this is like operating on a live body.
You have to basically make changes while the company is running. The content is being served, and the users are learning about the product. In Qumulo’s case, it was very important to determine the different moving pieces regarding content. There was internal content spread out as it usually is throughout confluence pages and the internal engineering documentation handbook. Interestingly enough, it was written in docs-as-code by an enterprising engineer in Hugo.
Looking at the content served by the marketing sites, we didn’t really have a lot to do with it, but we were looking at crossover and what was done similarly and differently. We’re looking at the content that sat on sub-domains and domains and was waiting to be reworked and used. What very often also happens is that someone who creates the content might not always be the maintainer of the content over a long period of time.
What I did then was to come up with a content strategy that I had to run by the main stakeholders. These are the VPs, the product owners, the owners for the engineering areas and whatnot, and basically convinced them that there was an easy path forward even though there were disparate forms of content to create.
From then on, it was important to identify a piece of the project that could be built as a proof of concept, which I then implemented by myself. At that time, it was a team of two people, so there was no one to reach out to. For instance, when I was at AWS, there was a system and a team that would go on your behalf and put infrastructure together.
If you’re trying to convince someone, you don’t have any resources. It’s very important to be very mindful of what’s out there, what’s available, and what you can jigger together for a good show to then build on as you go along. As it happens, I found a Jekyll template that was put together by my good friend and former colleague, Todd Johnson, from AWS. I chose it specifically over Hugo or other systems because it was a syntax that anybody could use. It was very important for a tiny documentation team to have allies on other teams, like engineering and product teams, who would be contributing to the documentation that we would then be curating.
Jekyll allowed us to do this because with the exception of a couple of more complex technical caveats, such as doing transclude or variable-based leans of content, most people could sit down and start writing Markdown because it was simple enough. After about two months, I delivered a proof of concept of the portal where I had to be the front-end developer, documentarian, designer of the initial nascent style guide, the writer of the initial batch of content, which was for a piece of the cloud platform and of the hardware platform, one of the super micro platforms, and then sell the idea.
Once the stakeholders saw that things weren’t as complicated as they seemed and the process is more amenable to the smaller team and more friendly towards other contributors, it was a lot easier to convince them to let me build out the whole thing, mask it with a corporate domain, and so on and so forth. For me, one of the main challenges has always been to almost translate my vision into something that would make sense to others.
I’ve been taking notes. There are so many things that I want to dig into in what you just said. Let’s start with this. As you’re building out your strategy and you’re selling that strategy internally, you’re making a wholesale change here and consolidating content from around your business into this new deliverable. How were you defining and then gaining buy-in on, for instance, the style guidelines? What was the process of designing the content that your audience is looking to read?
I don’t know if it’s a snarky answer to this question, but most people don’t care about the nuts and bolts as long as something works. I was lucky because, at that time, my manager was the VP of Engineering, which is very rare to have such a short reporting chain. At that time, it was me, then the VP of Engineering, the wonderful, talented Molly Brown, and then the CEO.
Having had such a short reporting chain meant that you don’t bring problems to people and complicated things for them to look at. You bring solutions. Design this, these people have looked at it, and they’re willing to work on this. In a way, it almost depends on what level you’re operating at. In most cases, people will not be interested in the nitty-gritty of things, and they’re interested in, “Does it work?”
Having a short reporting chain means that you don't bring problems to people and complicated things for them to look at. You bring solutions. Click To TweetI want to take a little sidebar to explain how I arrived at it. In my previous job, I was asked to work on an internal documentation portal for Oracle back when I was at OCI. There were a lot of moving pieces there as well because it was confluence based. We had to customize it as confluence based and integrate it with GRS, where people could file tickets about the content. We also had to do usability tests on the portal because, after a while, we realized that people were not finding the right content. When we weighed how the content was written and whether or not how the content was useful, it very quickly emerged that if they couldn’t find what they were looking for, the style didn’t matter at all.
What we ended up doing was treating it as a product usability test. We had 36 usability studies. I was assisted by an actual UX expert who would dive into the results and create the statistical breakdowns for the information. We would sit them down as any other UX study and say, “Find us information about how to integrate this service with API gateway.” We will click here and click here. “I don’t know. I’m lost.” We would start with that just as we would with the real product. What people often forget is they go straight for the style guide, wording, structured English, structured writing, and simplified technical English.
They often forget that documentation is a product in its own right with its own usability built-in and challenges in terms of searchability and usefulness. That’s another thing that people confuse, usability and usefulness. That’s something I learned during that project because usability is how easy and something to use, whereas usefulness is it’s easy to use but it assists you in terms of launching the service and understanding the product. There are all these factors. Once we nailed those down, it was more or less in my wheelhouse to go with whatever style guide I thought was best because that was less important than, “Is the help helpful?” I have a little anecdote speaking of, “Is the help helpful?”
That was one of the first textbooks I looked at when I was doing one of those degrees on the wall as a technical writing degree. I remember it was a horrifying textbook with a drowning man on the cover, purple in the face. The title of the book was, Is The Help Helpful? I’m not sure about the design choices for the book, but I always think about that bizarre cover when you think about the end goal because it’s easy to get lost in the weeds designing these systems ahead of the fact. As a matter of fact, they do grow organically.
As you get to know your user base, develop a new persona, and recruit new documentarians, your style guide will change because you realize suddenly maybe there’s more than one way to teach developers about passive voice. A lot of typical things that you get lost in the weeds on, but if you nail the usefulness first of these things, it will almost be secondary to delivering that doc as a product.
I like the usable versus useful. That’s interesting because, from a usability standpoint, it can work perfectly. If it’s not useful, it doesn’t help. You’re talking about an iterative process of getting closer to your end user by being able to measure the impact of that content in real time. That’s exactly what you should be doing. We see a lot of companies focusing on tech docs as a big part of their business. The impact or the end use of technical documentation isn’t just reading about how to use a product. It’s the adoption and the success of a product launch.
There are stories out in the marketplace of errant docs that have confused users so badly that they’ve blown up product launches. The importance of being useful and furthering the use of a product builds success in a business. It’s not just a thing happening over here because we all have to have tech docs. It’s a big part of a successful product launch, product usage, product adoption in the marketplace, and the success, in many cases, of a software business.
Let me respond to a couple of things you said. It’s interesting how obvious these facts are to us documentarians and how hard of a sell sometimes it is to those who are in charge of our resources, let’s say. I absolutely agree that documentation is a way into the beating heart of the company.
The joke I would always make back at AWS, for instance, when asking for something to be explained to me is that, “If I don’t get it, no one else will get it.” In fact, I’ll make sure of it because that’s how I write. I write what I know. I have another anecdote that may or may not be funny. I remember when I joined AWS. I have been documenting all the messaging services for about four years, including SQS, SNS, Simple Workflow that functions, and all that jazz.
One of the first weeks, I walked over to one of the developers and asked something about maybe dead-letter queues or some other feature. To answer my question, he opens up the docs. I said, “No, I’m writing the docs. Don’t use them as a source of truth.” That’s the problem. We need to develop a pipeline of what is true and how that truth is reflected. The docs in themselves are never necessarily the main source of truth. They’re like the filtered source of truth that you want the customers to know to take something away.
We need to develop a pipeline of what is true and how that truth is reflected. Click To TweetIt’s really telling because, at Qumulo, when I write internal release notes and public release notes, even if they’re about things that aren’t necessarily things we don’t want the customers to know, and maybe these are things the customers don’t need to know because they get lost in the weeds, they still need to be written very differently because you’re controlling the story or the narrative of how the product works to serve you.
I’ve seen companies err on the side of too much, too little, too technical, or not technical enough. There’s also the story of those who sell the product, not always considering the fact that these personas that people think come in after the sale, so we’ve sold it. Now we’re writing docs to the administrative and the developer persona. They come in beforehand, of course, during the investigation process. I’m not sure if the CTO is interested in this per se, but the people that the CTO sends out, “How easy the product to use is. Is there an API? Is there a REST API? Are there resources nicely structured? Are there good developer documentation and programming examples? Is there SDK documentation? What languages is the SDK documentation?”
These are all the things we try to imagine or think about when we think about people approaching the product. These are all the things that get thought of very often after the fact, or as you mentioned, as a checklist. It’s like, “We got to have documentation. What documentation do we have? Why?”
This is the epic battle we always have with the powers to be between the understanding that documentation is an inseparable part of the product, but also, it needs to be delivered and iterated in such a way, not like we’ve delivered it, and there it lives its own separate life, but certainly turned over every once in a while to create continuity for selling and showcasing and then working with the product. I do absolutely agree with that.
One of the things from way back at the beginning of this conversation that I keyed in on because of what I do is you talked about as you were consolidating content across the business, looking at what, for instance, marketing was doing. How much consistency do you try and build into the way that you communicate with the way that marketing is communicating, like from a terminology or a style standpoint? Is there any integration there?
I’ll use a phrase that my dentist friend likes to use, “We are not gods.” In a perfect world, I would come in and say, “Here’s a style guide. Let’s all get together and agree or disagree and get on with it.” The problem is that even if we were all friends in the best of the world, we can’t forget that these disciplines operate in different spaces.
Marketing is written very differently from the documentation. It’s all about value prop. What is this good for? Very quick understanding what are the features. What does it get you versus the competitors, and whatnot? Whereas docs would never do that. You can’t wander into their house and start telling them to make up rules.
It’s all about earning trust slowly and painstakingly with the various aspects and areas of the company that would maybe adopt your principles. This is a laborious process. It doesn’t come to bear right away. This has to do with ownership on your end, too. For instance, up until recently, we’ve had this acronym and abbreviation glossary that was not really owned by anyone. After our discussion with a few stakeholders, we decided team content is going to come along, and we’re going to own it. That allows us to create this source of truth. Next time someone is searching confluence or hits upon it, they hit upon a resource that’s then maintained. They don’t have to use it, but we’ve put it there for them.
I must admit that when I was younger, I was a lot more defensive back at AWS about marketing coming in and taking content from documentation and plopping it somewhere. One of my most frequent assertions was that, “They’re going to do it. Docs get turned over every time the product changes. Who’s going to maintain that static marketing side?”
As I’ve grown slightly older and smarter, I’ve realized that this has to be a negotiation that we have to enter into, where rather than telling folks what we want, we need to show the dangers of still content, bid throttle, and all that stuff, in turn, offer ways for them to iterate without necessarily owning their content because that’s how you get overloaded as well.
It’s a fine type of walk that you have to do to ensure that you provide the resources. I’ll take another detour again about providing resources and earning trust. One of the biggest challenges with the documentation portal at Qumulo was creating not necessarily the style guide but the best practices for contributing to docs-as-code because the portal is built with docs-as-code principles in mind.
Everything gets written in Git, Markdown, Jekyll, and certain stylistic guidelines from a code perspective. In the beginning, my approach was to simply give the resources to the engineer contributors and say, “Here they are.”
Even that was a little bit too top-down so instead, what I started to do a little bit over time was to create Slack channels and say, “We’re going to treat this like a clinic or an office hour. If you get stuck, you can come and ask questions. Maybe I’ll send you a link to one of these pages, but maybe workshop through it, so it becomes a mixture of both things.” It’s a tightrope walk again because I can always be advising people, but the trick is, if you get someone confident enough in this and they’re still in that channel, then they start advising others on your behalf. It’s almost like growing a network of allies in other organizations.
The main takeaway is about providing resources and then selling the internal resources as a tool that makes your life simpler and takes away some of the thinking. Speaking with one voice becomes a lot less complicated.
I remember back at SAP. We had some very complex guidance that was literally called One Voice. It was very thorough but difficult to keep in mind because it was a reference file that you had to open and go through to the right term. It was unclear who else was using it in this way. It was difficult to find examples. It was very good from a structural perspective. It was a little bit less organic from the perspective of earning the writer’s trust. That’s my approach to that.
When I think about the style guidelines, it’s difficult for the different silos of content in an organization to directly communicate. I almost think it’s hierarchal. Docs, marketing, service, and support are providing up to the broader business, and then up on top of that, there’s this top layer, which is, “We’re all going to spell the name of the company right.” Simple terminology rule.
Working down from there, we inherit from the next set so we have product names. Obviously, we should all be using the proper product names. You talked about acronyms. We should all be using the proper acronyms, but the way that we communicate at the technical documentation level is going to be different than the way that we communicate with support tickets or marketing content.
A fun side conversation from my end, when I got to this company, the first thing that I did was build out a tone of voice because that’s what somebody in marketing does when they join a new company. This is how we’re going to talk. It was common marketing stuff. It was supposed to be witty, wise, not arrogant, not sarcastic, helpful. But how do you turn that into something.
We worked through our product, built it out into Acrolinx, and implemented it with our front office team. Marketing had access to the BDR team customer success. It seemed to work with the audience that we’re communicating with. They enjoyed the tone, and it had the impact that we expected it to have.
Being a megalomaniac and wanting to touch everything in the business, I said, “Who else is making content?” The next group I found was support. They’re creating support tickets. I was like, “Fantastic. Here’s your filter. Please go build content this way.” Do you know who doesn’t think that my tone of voice is cute? Anybody is trying to solve a problem.
We learned really quickly that it couldn’t be one thing. It has to be, as you said, designed for the audience, and the purpose has to be useful. The fact that it might be fun and infinitely usable does not solve the problem, and it’s not useful to the audience.
One of the biggest takeaways here is that you can do everything technically right, but if it doesn’t solve the problem for the user, it doesn’t drive adoption and build retention around the use of a product. At the end of the day, that’s what docs is designed to do. The impact of your content is top-line growth, retention, and product success. It’s not just, “I’m going to teach you how to use the product.”
That’s what it does, but the business impact is maintaining and gaining new happy customers and successful customers around the product you sell. This has been super interesting. If somebody is reading this and they want to understand how to take their work in technical documentation to the next level, what’s the one thing that you would tell somebody entering this space that’s going to make them more successful?
You mentioned customers, so let’s talk about talking to customers. One interesting anecdote I have about customers and users at AWS is that most people don’t know this, but every single page in AWS documentation is keyed to a feedback form. If you fill out the form, it will have the URL to the embedded page. If the form goes wrong, maybe it’s a typo or some incorrect information, and then it will go somewhere. Most people have no idea where it goes. Where it actually goes is to the backlog of the writer responsible for that documentation. The interesting thing that has always amused me for those four years at Amazon is that AWS services are very tumultuous, so people get frustrated.
Maybe they’re studying for an exam and need to know how SQS works because these are foundational services. It basically underwrites the internet these days, eCommerce, and all that stuff. They might be under a tight deadline to complete a project that uses a service. Every once in a while, I’d say maybe 2 out of 10 times, and they’d go in saying all kinds of nasty things because they think they’re talking to a machine in terms of feedback, and then you’re right back to them, “Good sir. Thank you for your feedback. How can we improve this page?” They then get all embarrassed, and then you fix the problem together.
All joking aside, what’s excellent about a system like that where every single page is keyed to something. I haven’t seen that in a lot of places before or after Amazon. That’s a direct line to the user and customer. Very rarely do documentarians get that unfiltered. You mentioned customer success. Customer success is a great way of getting the information right. Again, whatever you’re getting from customer success is filtered to whatever conversation they’re having with a customer.
Customer success is a great way of getting the information right. Click To TweetIt might be accurate or a little bit influenced by the specific use case. You either need to interject by taking part in these conversations, or you need to find that more directing way of engaging the customer. A lot of the time, this is a pretty typical interview question for documentarians. “How do you know that what you did was successful?” The typical answer is metrics. Metrics don’t tell you the full story. The first thing I did after wiring the documentation portal for Qumulo was to connect it to Google Analytics, which is great. It tells you a lot of unexpected things.
For instance, it tells you, “Somebody Google translated this page into Japanese. I wonder if we should localize that page to Japanese.” Little things like that, but page views don’t tell the whole story. The stupid little widgets with this page’s useful app, like thumbs up or thumbs down, are completely useless. It’s been proven mathematically. It does not tell the full story.
What tells the full story is this non-algorithmic, very much heuristic feedback from customers. One of the first things I did when I joined Qumulo was to create a bit of a town hall with the engineer. At first, I wanted the perspective of what was their experience with documentation.
I have a long gripe session and record all the data. This was a little bit more difficult to finagle because you don’t want to blend the customers with too many questionnaires or things to respond to. I piggybacked our UX designers’ questionnaire. There are five or six questions about docs. I got a little bit of that data. I admit one of my initial failures was not to loop in the customer success folks early enough. After we rectified that, we started talking to them a little bit more. We had a third series of data points. By combining them all, we could get a sense of what was going on. It’s not a coincidence dimension usability testing a number of times to have this conversation.
It’s a very humbling experience to build something and then realize that all of your assumptions are wrong. This will always happen, and there’s nothing wrong with that. There’s nothing shameful about that. As intelligent writers, intelligent designers, UX developers, documentarians, and marketing folks, we always want the best for the user.
As Ambrose Bierce wrote, “The road to hell is paved with good intentions.” You have to moderate that desire with what’s useful to the customer. This is where that usability testing comes in. It can be in a variety of forms. It could be through long-form feedback. It could be through, and this is a little bit harder to do, sitting a person down and asking them to accomplish a task. It could be through certain accounting about interactions with customer success or support tickets and all that. It’s all important because it all challenges your assumptions about work and what doesn’t.
I’ll give you some examples from the past. Placement of navigational items. The documentation is perfect, but people do have no idea what to click on to get to the perfect documentation. That’s a very common issue, navigational hierarchies. Nesting things too deep, having versus not having breadcrumbs, collapsible menus, how many are too many, and little things like that. One issue that we ran into at building developer central at OCI was I wanted everything to have a learning flow.
You learned about something, what’s next? We always try to have something at the bottom of the page where, “Here’s what you can learn about next.” What was sometimes difficult to determine the most germane thing for the person to go onto was there were two or three different options, and that might have been successful sometimes and confusing at other times. In other words, putting yourself in the shoes of the user in every possible way and taking that feedback in stride, which is very complicated. You spent two months building something, and as someone comes to you and frankly tells you this is crap, you need to sit down and figure out why.
It’s also very important to sort out the visceral reactions from the actual actionable feedback. There will be moments where people will be responding viscerally, but all they meant to say was, “I wasn’t able to find the document as fast as I could,” when they said, “This is crap.” You can’t take things literally, and then you almost have to become a student of literary analysis and dig deeper and say, “What did you mean by that? If we change that, we change this one element. Would this work for you?” Again, it takes a lot of humility and time.
This is why I would almost say that when you are building out the documentation team, you almost have to have one person dedicated to metrics, customer engagement, questionnaires, and all that stuff. A big enough team on team is ten people. I could see a single person only dealing with that thing with the reception and the end result of the documentation. On a smaller team, you can have to share their responsibility with everyone else.
This has been absolutely enlightening. My biggest takeaway is the whole concept of useful versus usability. If somebody wants to continue this conversation, I assume you have someplace on LinkedIn where people could reach you.
I’m happy with folks to connect. I’ve been mentoring and having chats with folks for a couple of years now, and I’m always happy to answer any questions whatsoever.
Michael, thanks for hanging out. This has been great.
Thank you, Chris.
Important Links
- Qumulo
- Hugo
- Jekyll
- Is The Help Helpful?
- Acrolinx
- Michael Khmelnitsky – LinkedIn
- WordBirds – LinkedIn
- WordBirds – Home page
About Michael Khmelnitsky
Michael G. Khmelnitsky is a writer at heart. He is enamoured with words and uses them with purpose. In his professional life, he practiced highly usable, functional language across many technical disciplines. He approaches what he describes and explains as an integrated whole, from the shortest string to the most critical REST API resource. He shares what he learns and mentors other writers. In his personal life, he pursues beauty in the composition and translation of poetry.
