Docs and UX: It's a collaboration, not a competition

Go to the profile of Alexandra Gifuni
Alexandra Gifuni BlockedUnblockFollowFollowing Mar 27

A look at how technical documentation and UX are stronger together

I recently read
I recently read UX in Flux: Where We're Going, We Don't Need Docs, a great piece by Karen Kesler. In it, she argues that if we continue to move towards better UX (user experience), technical documentation can effectively become obsolete.

This argument is not a new one, and it is difficult to ignore. It's something I have been reading about since I started as a Technical Writer at my previous employer 7 years ago. The thought of my work becoming obsolete worried me so much at that time that I made a point to delve into UI (user interface) design --- devoting about 15% of my work week to collaborating with the development team to create intuitive wireframes, with the aim of improving the UX.
这个论点不是新的,很难忽视。自从我7年前在我的前任雇主担任技术撰稿人以来,这是我一直在阅读的内容。我的工作变得过时的想法让我非常担心,当时我特意深入研究UI(用户界面)设计 - 我将大约15%的工作时间用于与开发团队合作创建直观的线框图,旨在改善用户体验。

Starting at the ShareGate division of GSoft nearly 3 years ago saw me
从近三年前GSoft的ShareGate部门开始,我看到了 drowning in a backlog of unwritten documentation. I didn't have time to think about helping to improve the app's UX, all I had time to think about was writing the best documentation possible to meet the needs of our customers. Now that I'm a Technical Content Manager, things have again evolved. I need to consider --- more than ever before --- how technical documentation fits into our world. Our product has been continuously lauded by customers to be one of the
积压的未经编写的文件。我没有时间考虑帮助改进应用程序的用户体验,我有时间考虑编写最好的文档以满足客户的需求。既然我是技术内容经理,事情又一次发展了。我需要比以往任何时候都更加考虑技术文档如何融入我们的世界。我们的产品一直受到客户的称赞,成为其中之一most user-friendly solutions for their needs that they have encountered on the market. We have a dedicated team of developers and designers who listen to customer feedback attentively and use it fuel real, measurable improvements to our app every few months. These include improvements to the UX though design, tooltips, descriptions-in app, and so on. So, you'd think with all those, there'd be less hits on our knowledge base as time progresses, right?


In fact, it seems that UX-specific improvements to the app do not affect the number of hits on our knowledge base at all. As the number of returning app users rise, so does the amount of returning users on the knowledge base.

I'm sure there are more than a few theories we can delve into on why this is the case, but I'm just going to focus on one. The relationship between UX and technical documentation is a collaboration, not a competition. Consider the following:

Complex errors require complex solutions

Depending on the kind of software you work on, you might face problems that can't be solved through good design or guidance in-app.

Take error troubleshooting, for instance. This has to be the type of technical documentation that gets the highest amount of hits on our knowledge base. That's because whenever possible, we offer the customer a detailed step-by-step solution to help them resolve their error. These solutions can end up getting pretty complex, sometimes requiring that the customer uses scripts or even third-party apps to help solve the issue. But that's the point, right, to
例如,进行错误故障排除。这必须是技术文档的类型,在我们的知识库中获得最高的点击量。这是因为我们尽可能为客户提供详细的逐步解决方案,帮助他们解决错误。这些解决方案最终会变得相当复杂,有时需要客户使用脚本甚至第三方应用程序来帮助解决问题。但这就是重点 solve the issue . It may not be elegant, but the customer has a job to do and we help them get it done. Solving complex errors require detailed solutions you just can't include through the UX alone. That doesn't mean that we leave customers to find the solution themselves --- every time they get an error, you can bet there'll be a link within the app to the exact article that helps them solve it. And as the app evolves, new types of errors are inevitable, and so are new solutions; documented in the knowledge base, of course.
。它可能不是很优雅,但客户有工作要做,我们帮助他们完成工作。解决复杂的错误需要详细的解决方案,而这些解决方案只能通过UX来解决。这并不意味着我们让客户自己找到解决方案 - 每次他们收到错误时,您都可以打赌应用程序中有一个链接可以帮助他们解决问题。随着应用程序的发展,新类型的错误是不可避免的,新的解决方案也是如此;当然,在知识库中记录。

People still like searching for answers on their own

If you look at the statistics, we are still far from the world alluded to in Kesler's piece, where UX is so good that customers do not need technical documentation.
如果你看一下统计数据,我们在Kesler的文章中提到的世界还很远,那里的用户体验非常好,客户不需要技术文档。Study after study has shown the importance customers place on self-service. Essentially, they still have a lot of questions, and they want to be able to find the answers quickly and effectively.

Think about it this way; in-app text and intuitive design help the customer run a specific process in the moment, but it does not answer their wider, broader questions. Take video games as a prime example. As you play, the game will work in tutorials to teach you the controls, how to jump and move forward, and special combos, but it can't (or won't) always help you when you are stuck. Whether it's a maze-like dungeon you can't navigate out of, or a seemingly unbeatable boss, there are things you might need extra help figuring out. That is why intricate guides like those found on
以这种方式思考;应用程序内文本和直观设计帮助客户在当下运行特定流程,但它无法回答更广泛,更广泛的问题。以视频游戏为例。当你玩游戏时,游戏将在教程中用于教你控制,如何跳跃和向前移动,以及特殊组合,但它不能(或不会)在你被困时总是帮助你。无论是一个迷宫般的地牢,你都无法驾驭,或者看似无与伦比的老板,有些事情你可能需要额外的帮助才能搞清楚。这就是为什么复杂的指南,如那些发现IGN are immensely popular.

In software, customers have similar blockers all the time that aren't answered in-app (on a fundamental level of course, unbeatable bosses notwithstanding). Think about questions on licensing, pricing, encryption, data collection, and so on. Linking to an external knowledge base where customers can search for these answers is invaluable.

The price of excluding this essential information from an easy-to-search knowledge base is more calls and emails coming to your Support team. If a question can be answered in the documentation, having the Support team deal with it is not the best use of their time and resources.

Interested to know more about how much technical documentation can help your Support team? Check out my post,
Want to write great technical documentation? Work in Support

With integrations, we can now have the best of both worlds

Thanks to apps like
感谢像这样的应用Zendesk allowing you to integrate your knowledge base within an online app, you can marry documentation and UX like never before.

Sure, your UX design should still be smooth, and yes, you should still make the best use of tooltips and in-app wording as you can. But with integrations, when a customer runs into a blocker, they don't even need to leave the app to find help. They can click a button that will trigger a pop-up or drop-down to search the knowledge base, and the answer will be described in a window right within the app.

The industry calls leveraging resources together like this an
业界呼吁像这样一起利用资源omnichannel content strategy. It has been shown to be very effective for customer satisfaction as a whole --- that's because it puts the UX and the technical content to work in unison, not in parallel.
。它已被证明对整体客户满意度非常有效 - 这是因为它使用户体验和技术内容齐心协力而非并行。