Contextual AI, an enterprise RAG company, announced the general availability (GA) of the Contextual AI Platform, helping enterprises build specialized RAG agents to support expert knowledge work. While there is broad consensus that general-purpose AI agents are poised to streamline many generic tasks, Contextual AI believes that specialized RAG agents will instead be required to […]

dbt Labs, experts in analytics engineering, has acquired SDF Labs, the team of former Meta and Microsoft engineering leaders behind SDF, a data transformation technology. The acquisition will integrate SDF’s multi-dialect, dbt-native SQL comprehension capabilities into dbt, delivering improvements to dbt performance and enhancing the developer experience, efficiency, data velocity and data quality. the SDF […]

Foxit, a provider of PDF and eSignature products and services, helping knowledge workers to increase their productivity and do more with documents, announced the launch of Foxit AI, a standalone web-based AI platform that delivers document-centric AI capabilities to users across industries. Foxit AI offers a comprehensive suite of features, including AI-powered chat assistance, document […]

Contentstack, a composable digital experience platform (DXP) provider, today announced its acquisition of Lytics, a real-time customer data platform. The acquisition, which closed in December of 2024, brings comprehensive audience insights, content analytics and profile management to the Contentstack platform, unlocking real-time personalization for known and unknown users. Major global brands including Kraft Heinz, Mondelez, […]

This week we feature articles from Melanie Mitchell, and Maria Mouschoutzi. Additional reading comes from Chia Jeng Yang, Nilay Patel & Mustafa Suleyman, Kate Knibbs, and Sayash Kapoor & Arvind Narayanan, and Louie Peters. News comes from Graphlit, RWS, Brightcove, and Grammarly & Coda. Next issue arrives January 22. All previous issues are available at https://gilbane.com/gilbane-advisor-index Opinion / Analysis OpenAI’s o3 […]

[TLDR] A recent study, "Listen to Your Users: The Effect of Usability Evaluation on Software Development Practice," by Marta Kristín Lárusdóttir, an Associate Professor at Reykjavik University, provides insights of value to tech writers into the impacts of usability evaluation methods on software development.

Related: A Systematic Review of Software Usability Studies

Software has slithered into every corner of our lives, quietly elbowing its way into our shopping carts, Netflix queues, and even the spreadsheets where Karen from accounting secretly plots world 🌍 domination.

It’s the invisible concierge of modern existence, fetching cat memes while scheduling your root canal. Try to avoid it, and you’ll find yourself in a standoff with a self-checkout machine that seems to know your darkest secrets but still insists you didn’t bag the kale.

Widespread reliance on software apps makes usability critical. Tech writers are essential in creating clear, user-friendly documentation that reduces frustration and enhances usability satisfaction with software products.

What Is Usability?

"The extent to which a product can be used by specified users to achieve specified goals with effectiveness, efficiency, and satisfaction in a specified context of use."

Source: International Organization for Standardization (ISO) 9241-11, Ergonomics of human-system interaction—Part 11, Guidance on usability

Photo: David Travis via Unsplash

Why Evaluating Usability Matters

Usability evaluation is like watching someone try to fold a fitted bed sheet—it reveals how well (or catastrophically) people interact with a system.

When system design leaves users bewildered, tech writers are saddled with the fallout, scrambling to cover up the cracks with explanations that shouldn't have been necessary to create in the first place.

Related: The 10 Most Common Reasons For Poor Usability

Software Usability Lessons Learned

Usability Testing Gold Standard: The Think-Aloud Method

The Think-Aloud method is the gold standard for usability testing. It’s like eavesdropping on someone's inner dialogue while they navigate your software—only they know you're listening, and they're kind enough to talk out loud so you can hear their thoughts.

This technique helps evaluate usability by having users discuss their thoughts, decisions, and frustrations as they interact with a product or system. Their real-time narration shows you what they find easy, confusing, or difficult to use. Watching actual users struggle, triumph, or groan through real-world tasks uncovers challenges you might not otherwise notice.

Why Heuristic Evaluations Alone Are Insufficient

While helpful, heuristic evaluations can't compete with the raw, unfiltered honesty of a real-world user saying, "Wait, WTF am I supposed to click?"

Source: Offline Granny

Heuristic evaluations and the Think-Aloud method are like two very different dinner guests at a usability testing party.

The heuristics expert arrives early, armed with a checklist and a knowing smirk, pointing out all the theoretical flaws in the seating chart before anyone arrives. Meanwhile, the Think-Aloud participant strolls in fashionably late, sits down, and narrates their dinner experience in real time—“Why is the soup cold?” or “I can’t figure out which fork to use.”

Related: 10 Usability Heuristics for User Interface Design

Photo: David Travis on Unsplash

Diverse Evaluation Methods Yield Richer Usability Insights

Mixing usability evaluation methods is like combining ingredients in a recipe—you get more flavor and texture.

Heuristic evaluations are fast, efficient, and perfect for catching broad issues early on. The Think-Aloud method, on the other hand, takes more effort but reveals what goes wrong when the guests (or users) interact with the product. Together, they make a well-rounded pair, offering the expert’s foresight and the user’s experience to create a more usable product.

Heuristic evaluations establish the structure, while incorporating real-world observations provide you the messy, juicy details. Together, they tell the full story of how users actually engage with a system.

For tech writers, this means you can predict the wild variety of ways people will tackle a task and create docs that speak to everyone, from the fearless power-user blazing through menus to the newbie poking buttons as if they might explode.

Tech Writers Should Prioritize Updates To Documentation That Align With High-Impact Usability Fixes

Tech writers should consider making updates to their documentation that align with high-impact usability fixes. Think of it as triaging a dinner party gone wrong—you deal with the kitchen fire before worrying about the slightly overcooked green beans.

This means playing the alignment game—focusing on updates that tackle the usability quirks most likely to trip users up. The goal? Craft content that explains and hands users the tools to succeed, even when the system isn’t optimized to work as easily as it might otherwise.

This gap between “it works” and “it works for humans” is where usability experts, designers, and yes, technical writers, swoop in to save the day. But until usability as a priority gets a permanent seat at the development table, the effort to make software truly user-friendly will remain the odd one out, quietly waiting for its turn to shine.

High-impact fixes address the parts of a system where users are most likely to stumble, curse, and possibly throw their smart phone across the room. Updating the documentation to match these fixes saves users from unnecessary agony and makes you look like the hero who actually understands their plight.

Plus, it’s a smart way for you to work. Why should you spend hours perfecting instructions for obscure features no one uses when you could tackle the big stuff everyone complains about? It’s like choosing to patch the roof instead of rearranging the furniture while rain pours in.

And let’s be honest: when you align your updates with what developers are fixing, you’re not just helping users—you’re making the whole team look good. Who doesn’t love a little mutual back-patting?

Photo by Luis Gomes

Why Don’t Software Devs Focus On Usability, Anyway?

The study didn't just lift the curtain on software developers and usability—it exposed a truth we all know, but don't love to admit:

Developers, no matter how much they appreciate usability data, are stuck in the land of tight deadlines and impossible to-do lists. They can't fix everything, so they cherry-pick the disasters that scream the loudest.

Software developers don’t focus on usability as much as you’d think because deadlines, feature requests, bug fixes, and management’s insistence on adding “just one more thing” tend to push usability into the corner like the kid no one wants on their dodgeball team.

It’s not that they don’t care; it’s just that “Does this button make sense?” tends to lose out when “Does the app crash?” is still on the table.

And, let’s not forget the classic “developer goggles” syndrome. Developers know how the system works because they built it, so they assume users will magically understand it, too. Add a sprinkle of budget constraints and a dash of “ship it now, fix it later,” and you’ve got a recipe for a product that sometimes feels like it actively dislikes its users.

Tech Writers: Don’t Let Usability Take The Back Seat

As much as you’d like to think perfect software falls from the sky, it’s a team sport, and technical writers are on the front lines. When usability takes a back seat, you’re explaining away the quirks, translating chaos into clarity, and ensuring users don’t toss their laptops out the nearest window. But imagine a world where usability isn’t an afterthought. Imagine if technical writers, developers, and designers worked together from the start to create systems that don’t just work—but work beautifully.

It’s not just a dream; it’s a goal worth striving for. In the end, making technology accessible and delightful isn’t just good for users—it’s good for all. So let’s stop patching over cracks and start building bridges.

Who’s in?

Unstruk Data Inc, an AI software provider, introduced the Graphlit Agent Tools Library, now live on GitHub (github.com/graphlit/graphlit-tools-python). This new toolkit builds on Graphlit’s RAG-as-a-Service platform capabilities, enabling developers to rapidly build AI agents that streamline data handling and LLM-driven workflows. By eliminating infrastructure complexities, Graphlit positions itself as a comprehensive solution for organizations seeking to harness large […]

Brightcove, a streaming technology company, is sharing enhancements to its platform through strategic partnerships to enhance the video content creation, distribution and monetization, and to help customers build more cohesive, easy-to-deploy martech stacks. The relationship with Acquia is part of a broader initiative to co-sell and co-market integrated solutions that drive mutual customer success. For […]

Grammarly, an AI assistant, announced its intent to acquire productivity platform Coda. Coda’s CEO and Co-Founder Shishir Mehrotra will become the CEO of Grammarly. The addition of Coda’s AI tools and surfaces aims to transform Grammarly into an AI productivity platform for apps and agents where customers can unlock access to company knowledge, generative AI […]

RWS, a provider of technology-enabled language, content and intellectual property solutions, announced the availability of Tridion Sites 10.1. The latest version of RWS’s web content management platform includes several new features that enable more granular control and management of global content, multilingual marketing campaigns and digital experiences. New features include: New integrations and partnerships include TravelLaunch […]

My personal quick reference

What could go wrong?

When I talk to writers about this, I state the case strongly: every topic should be able to fit anywhere. That always provokes some pushback, which is good. Of course it’s not really so, in practice. There are many combinations of topics that are just never going to happen. However, on a large scale, with hundreds or thousands of topics, there are many, many plausible combinations, some of them completely unexpected.

In fact, there are so many plausible combinations, you might as well not worry about the impossible ones. You might as well just go ahead and write each topic as if you had no idea what parent topic it was going to be pulled into.

That’s what we mean by “unleashing” your content with DITA. It’s the combinations of topics that bring the value, not the individual topics themselves. If you draft each individual topic so that it’s eligible for the largest possible number of combinations, you’ve multiplied the usefulness to the user (yes, and the ROI, and the technical efficiency) of the information in that topic. For any given topic, it’s true, there may be only three or four conceivable combinations in which it could make sense. For some, there might be hundreds. You’re not going to know unless you write for reuse in every case.

Once we’ve put this into action, we can go back to the managers and gurus and say, now you’ve really got ROI; now you’ve really got efficiency. Because we’ve given you something that is worth investing in, something that’s worth producing efficiently. Something that can delight readers with its usefulness and its elegance. This isn’t just content, this is writing.

In any information set, every component should be able to roll up into what is ultimately a single top-level summary. We know most readers don’t come in through the front door, but in principle you can provide the reader with an entry point that fully sums up what’s in the information set. From there they can drill down into more and more detailed levels. (Readers can be very easily trained to do this, because they have learned from their previous reading to scan for summary-like information and use that to judge whether it’s worth reading on for more detail.)

If each level is itself a rolled-up collection of subordinate units, and so on in turn down the ranks, what you are offering is a set of pages in which each page is itself a table of contents. The content is the navigation and the navigation is the content.

Picture this single page sitting at the apex of a pyramid. It contains (describes) everything that is included in that pyramid. Not that many people are ever going to actually read that page, but we need it to be there, because it defines the pyramid.

The bigger the pyramid, the higher level the information in its top node is going to be. So, for a very large information set, that single page is going to be very general. Each of its immediate child pages will be a level more detailed, and each successive level is going to be more detailed, until you get to the bottom “leaf” level where a topic describes only itself.

 

The most disorienting thing about learning structured writing is modularity. There are a lot of things we’ve learned about writing that we have to unlearn; this is the most fundamental of them. This is way bigger than deciding it’s OK to dangle a preposition.

Modularity means, in practice, conveying meaning in free-standing chunks instead of in a unified stream. Why is it so great to be free-standing? What does that get me, from a purely authoring perspective? (Remember, we’re still excluding managerial and technical perspectives from this conversation. You folks can come on back later.)

In mature DITA writing, many topics are built up automatically from component topics. Done well, these composite topics look like you lovingly handcrafted them with sections, section titles, section detail, overview material, and so on. In fact, you threw them together on the fly from component topics that you happened to have lying around.

How good your built-up topics are depends on how good those component topics are. How good the components are is largely a function of how well each one delivers meaning on its own, without having to wait for any other component to its job.

A composite topic that looks and reads like a composite topic is a failed composite topic. It needs to look and read like it was specifically conceived for this particular user at this particular moment. We want its component topics to match, in tone and style and scope, so well that they look like they were all written at once for this specific collection.

You’re working on a building, from the roof down and from the foundation up at the same time. You know what you need your built-up composite topic to do, which influences how to you’ll define and select or draft its component topics. At the same time, as your component topics come into being, they’ll influence the scope, scale and ultimately the effectiveness of the composite topic you’re building from them. In my experience, it’s when this process gets rolling that you really start to feel like you’re doing interesting, useful writing. This is where the fun starts.

I’m reprising something I put up on this site about five years ago (lightly edited), because it still comes up in conversation occasionally and it’s fun stuff to talk about. Goes a little bit like this:

Writing has a tense, complicated relationship with speech. Good writing gives the illusion of resembling speech, or being derived from speech. But writing that is transcribed from speech is generally bad writing. It doesn’t feel like real speech. Some writing that does feel like real speech seems stilted when you read it out loud. The speech that writing evokes is imaginary speech, speech that takes place in your mind’s ear.

Often someone says something in a meeting that captures a thought perfectly. It may even seem elegant, like something that everyone knows but that hasn’t been expressed so well until now. Someone will say, “Get that down.” Later, at editing time, it turns out to make no sense at all. The context has changed, of course: what’s said in a meeting grows out of the experiences of everyone there, complete with unspoken assumptions, agreements and compromises. Text has little or no context. It appears out of nowhere, bearing all of its antecedents within itself. It has no hope of matching the immediacy of a spoken conversation. But we can rely on it to a degree that we can’t rely on our memory of speech.

Let’s leave aside, for now, the whole technical thing. Let’s separate creating content from building deliverables, at least abstractly. Let’s just talk about how we can use DITA to create beautiful, thrilling texts.

The first thing to acknowledge is that DITA is not just an XML-based way of producing the same kinds of products we used to push out with Framemaker. (That would be DocBook.) DITA is so much more than that. It’s a new way of writing. It invites us to look at our writing in a completely different way.

When people talk about DITA they almost always talk from one of two overlapping perspectives: the technical guru or the publication manager. Writers have reason to care about some of the same things those two care about, but neither focuses on what really matters to tech writers.

• To the technician, DITA is mainly about all the awesomely efficient processing and automation you can do. To a writer, efficiency is great as a means to get good writing in front of readers. It’s not an end in itself.

• What sells DITA to a manager is the cost savings from reuse and processing efficiency. Writers care about saving money too — to hire more writers with, of course — but investment only matters to us if it’s in pursuit of better content.

I suspect that’s why there are a lot of DITA-based help sites out there that aren’t really much better than the old paper or PDF or Winhelp or Dreamweaver products that they replaced. Gurus and managers have reconfigured their thinking, but writers haven’t. We’re still trying to write the kind of stuff we grew up writing, and trying to jam it into a new kind of container. But this new container demands a new kind of content.

There has been a steady stream of upbeat, expansive reports on the future of mobile marketing and advertising (most of which—if you track these sorts of predictions—tend to wildly overshoot their mark), coupled with prognostications that the internet as we... Astoria

There appears to be a growing trend among content publishers of using targeting technologies to focus and solidify their relationships with their customers, rather than passing customer data to their ad network ecosystem. Although the benefits of this type of ... Astoria

Mobility trends are clear and undeniable, it is not just that the global market for mobile devices is now measured in the multiple billions, but also that the next generation of mobile devices has gained traction at a remarkable rate.... Astoria