Search Engine Optimization (SEO) has been our guiding star for years. It has taught us how to craft meta descriptions, what keywords to sprinkle throughout our content, and how to structure articles so that Google will reward us with that sweet, sweet page one spot.

But something's been happening recently. Algorithms are getting smarter. Google isn't the only game in town anymore.

Answer Engines—like ChatGPT, Siri, and MicroSoft’s CoPilot—are changing how we interact with information. You no longer have to type keywords into a search bar and scroll through a list of results.

You can ask your device a question, and boom, an answer comes back to you. No endless clicking, no wondering whether you're on the right page. You get the info you need. Instant gratification.

Read more

APIs power the digital world, but without clear, well-structured documentation, even the best APIs can be frustrating to use. Whether you’re a technical writer, developer, or anyone working with APIs, mastering API documentation is essential for creating a seamless developer experience.

Join API documentation expert Mark Wentowski (Docs Geek) for the Mastering API Documentation Workshop Series – Summer School Edition, offered in two sessions this summer:

• Summer 1: Begins May 5

• Summer 2: Begins July 7

This seven-course series covers everything from API fundamentals and structured data to OpenAPI, authentication, and refining API references. Each session is designed with hands-on exercises using industry-standard tools like Swagger UI, Postman, Curl, and Mermaid, ensuring you gain practical, real-world skills.

Don’t miss this opportunity to sharpen your API documentation expertise with guidance from an industry veteran. Choose the session that fits your schedule and take your API documentation skills to the next level!

About the instructor

Mark Wentowski (Docs Geek) is an API Documentation Specialist with over 13 years of experience producing global, web-based, developer-to-developer documentation for web services, libraries, and other software products.

Summer Session 1 — Class begins May 7, 2025

🗓️ May 5 — Course 1: Understanding APIs

This class introduces the fundamentals of APIs, covering their purpose, how they function, and how to interact with them using tools like Curl, web browsers, and JavaScript applications. It also explores API documentation, its key components, and the tools used to create and maintain it, with hands-on exercises in Swagger UI.

🗓️ May 12 — Course 2: Structured Data & JSON

This class explores structured data with a focus on JSON, covering its format, objects, arrays, and nesting. It includes hands-on exercises with Swagger UI and Postman to construct and send JSON requests, interact with APIs, and handle authentication.

🗓️ May 19 — Course 3: OpenAPI Deep Dive (Part 1)

This class provides a deep dive into OpenAPI and YAML, covering key components like the Info Object, servers, paths, operations, and responses. Through hands-on exercises in Swagger Editor and Curl, participants will practice structuring API definitions, troubleshooting errors, and making API requests.

🗓️ June 2 — Course 4: OpenAPI Deep Dive (Part 2)

This session focuses on query parameters, authentication, and CRUD operations in OpenAPI and Curl. Participants will practice constructing API requests, handling security schemes, and documenting API interactions using Curl and Swagger UI.

🗓️ June 9 — Course 5: API Flows & Diagramming (Part 1)

This session covers user journeys, API flows, and diagramming with Mermaid. Participants will map user interactions, translate them into API flows, and practice authentication flows in a React Admin Panel.

🗓️ June 16 — Course 6: API Flows & Diagramming (Part 2)

This session focuses on the sequence diagramming of API flows, including user login, admin login, and patron actions, using tools like Curl and Mermaid. Participants will diagram and analyze authentication and admin/patron API flows, then apply their learning with hands-on exercises using Postman.

🗓️ June 23 — Course 7: Refining API References

This session focuses on refining API references, covering topics like the difference between formal and informal elements, documenting endpoints, fields, and status codes, and writing error messages. Participants will practice these concepts through hands-on exercises in the Swagger Editor, improving the ability to create clear and detailed API documentation.

Register

Summer Session 2 — Class begins July 7, 2025

🗓️ July 7 — Course 1: Understanding APIs

This class introduces the fundamentals of APIs, covering their purpose, how they function, and how to interact with them using tools like Curl, web browsers, and JavaScript applications. It also explores API documentation, its key components, and the tools used to create and maintain it, with hands-on exercises in Swagger UI.

🗓️ July 17 — Course 2: Structured Data & JSON

This class explores structured data with a focus on JSON, covering its format, objects, arrays, and nesting. It includes hands-on exercises with Swagger UI and Postman to construct and send JSON requests, interact with APIs, and handle authentication.

🗓️ July 21 — Course 3: OpenAPI Deep Dive (Part 1)

This class provides a deep dive into OpenAPI and YAML, covering key components like the Info Object, servers, paths, operations, and responses. Through hands-on exercises in Swagger Editor and Curl, participants will practice structuring API definitions, troubleshooting errors, and making API requests.

🗓️ July 28 — Course 4: OpenAPI Deep Dive (Part 2)

This session focuses on query parameters, authentication, and CRUD operations in OpenAPI and Curl. Participants will practice constructing API requests, handling security schemes, and documenting API interactions using Curl and Swagger UI.

🗓️ August 4 — Course 5: API Flows & Diagramming (Part 1)

This session covers user journeys, API flows, and diagramming with Mermaid. Participants will map user interactions, translate them into API flows, and practice authentication flows in a React Admin Panel.

🗓️ August 11 — Course 6: API Flows & Diagramming (Part 2)

This session focuses on the sequence diagramming of API flows, including user login, admin login, and patron actions, using tools like Curl and Mermaid. Participants will diagram and analyze authentication and admin/patron API flows, then apply their learning with hands-on exercises using Postman.

🗓️ August 18 — Course 7: Refining API References

This session focuses on refining API references, covering topics like the difference between formal and informal elements, documenting endpoints, fields, and status codes, and writing error messages. Participants will practice these concepts through hands-on exercises in the Swagger Editor, improving the ability to create clear and detailed API documentation.

Register

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

You're in luck if your content strategy could use a tune-up—or a complete overhaul. The content experts at Comtech Services are offering three upcoming training workshops to help you sharpen your skills and streamline your content operations. Whether you prefer instructor-led, in-person training or the convenience of virtual learning, there's an option that fits your schedule.

From harnessing AI in content strategy to building effective taxonomies and mastering advanced reuse strategies, these workshops will help you work smarter, not harder. Keep reading to find the session that's right for you!

Incorporating AI into Your Content Strategy

📅 May 6 – June 24, 2025
🔗 Details: https://comtechservices.com/training/ai-content-strategy/

If AI hasn’t yet infiltrated your content strategy, it’s only a matter of time. (It’s already in your inbox, your search results, and probably judging your Spotify playlists.) This workshop teaches you how to harness AI, ensuring your content operation gets more intelligent, faster, and slightly less soul-crushing. You’ll explore real-world applications of AI in content creation, management, and governance.

This workshop is available both in-person and online. Save 10% off the registration costs when you use discount code — TCW — at checkout.

Creating an Effective Taxonomy

📅 May 7 – June 25, 2025
🔗 Details: https://comtechservices.com/taxonomy/

Some people are naturally organized. Then there are the rest of us who have 47 open browser tabs and still can’t find the document we just downloaded. Taxonomy is the secret to a well-structured content world, and this workshop will teach you how to create order from chaos. If you’ve ever muttered, “Why is everything so hard to find?,” this one’s for you.

This workshop is offered online. In-person workshops for teams can be scheduled for 2 days onsite. Contact CIDM for details.

Save 10% off the registration costs when you use discount code — TCW — at checkout.

Advanced Reuse Strategies (India Standard Time)

📅 May 8 – June 26, 2025
🔗 Details: https://comtechservices.com/training/dita-reuse/

This one’s for the DITA diehards—those who get unreasonably excited about structured content and the thrill of reusing components across multiple deliverables. If your idea of a good time involves maximizing efficiency and reducing redundancy, this workshop will teach you advanced reuse techniques to make your content work twice as hard, so you don’t have to.

Plus, this session is scheduled for India Standard Time, making it ideal for global professionals who want to improve their DITA skills.

This workshop is available both in-person and online.

📌 Pick your workshop, register now, and get ready to make your content work smarter.

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

A few years ago, I attended a technical writing conference where a panel of well-known documentation consultants held court. They spoke with the confidence of people who had seen dark things like entire documentation systems erased by an intern who "didn't think it would actually delete." They debated metadata strategies the way some people argue about politics at Thanksgiving. The kind of deep, expert-level discussion that makes you feel both inspired and slightly inadequate.

But looking around the room, I noticed something unsettling. Most of these experts who shaped how documentation is done in the modern age were in their late fifties, sixties, or even seventies. Some had already started scaling back, slipping into partial retirement, consulting "only on projects that truly interest me" (translation: no, I will not fix your broken website again).

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

And that's when it hit me: What happens when they all retire simultaneously?

Unwritten Rulebooks (No One Bothered to Write Down)

For decades, these folks have been the unofficial keepers of the industry. They're the ones who fought for structured content before anyone even knew what that meant. They convinced entire companies that documentation should be more than a last-minute Word doc someone slaps together at 4:59 PM on a Friday.

They are the people who:

• Invented the standards we take for granted.

• Wrote the books we pretend we've read.

• Taught the courses that made us believe we could actually do this job.

But here's the problem: so much of their expertise lives in their heads. And those heads are dangerously close to being retired and relocated to a beach somewhere, never to be troubled by another information architecture crisis.

The 'Figure It Out Yourself' Future

If you think about it, the technical documentation industry is oddly fragile. Companies often don't invest in documentation until something goes horribly wrong—like a software release so unintelligible that the support team quits en masse.

Now imagine that, on top of that, all of the industry's best consultants and educators vanish.

Who steps in to:

• Train the next generation of documentation leaders?

• Convince CEOs that investing in structured content is worth it?

• Stop a well-meaning but disastrously uninformed team from using Microsoft Excel as a knowledge base?

It's not that there aren't younger people in the industry—we don't have nearly enough of them in leadership positions. Right now, a frightening number of companies rely on a single documentation expert to hold things together, and that person's retirement is, at best, a vague "someday" that no one plans for.

The Mass Exodus: A Crisis in Waiting

Picture this: a year from now, a dozen of the most well-known documentation experts simultaneously retire. Suddenly, there's a void. Companies that rely on these experts for training and strategy start scrambling. Who else understands content governance at scale? Who else can convince a room full of executives that documentation is a business asset, not a cost center?

It's like waking up one day and realizing all the plumbers have retired, and now you're stuck with an overflowing toilet, a YouTube tutorial, and a wrench.

Why We Should Panic (But in a Productive Way)

Before we start accepting our bleak, documentation-free future, let's talk about what we can do:

1. We need structured knowledge transfer.

   • Veteran experts should be mentoring new professionals, writing down their battle-tested strategies, and ensuring they don't take their expertise to the grave (or, you know, to a retirement community in Florida).

2. We need to make documentation leadership attractive to younger professionals.

   • Now, becoming a documentation consultant is like becoming a jazz musician—respected by a niche audience but not a mainstream career choice. We need to change that.

3. Companies need to realize that an expert-level documentation strategy is not replaceable.

   • Organizations should hire documentation specialists before the last experts leave, not after realizing the product is unusable without them.

A Retirement Party We Can't Afford to Ignore

Technical documentation as an industry is at a crossroads. If we don't invest in the next generation of experts—consultants, educators, and documentation strategists—we're looking at a future where companies try to automate away problems they don't fully understand, and the only available documentation training is a two-hour webinar hosted by someone who just discovered Markdown last week.

So, if you're an industry veteran, here's my plea: write it all down before you retire. Mentor someone. Record a video explaining why metadata matters. Start a blog. Write a book (or three). Please do something to ensure that when you finally sign off for good, the rest aren't left googling "How to create a sustainable documentation strategy " and getting a bunch of AI-generated nonsense in return.

Otherwise, the future of tech comm might be one long, desperate, less-than-helpful Slack thread.

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Let’s be honest: your help site probably needs work. Users likely can’t find what they need. The search function may serve up everything except the right answers. And despite your team’s best efforts, critical documentation hides so deep it might as well be on ancient scrolls.

Good news: You can fix that.

Even better news: It won’t cost you a dime to find out which changes will deliver the most bang for your buck.

The folks at Heretto — makers of a powerful component content management system in use by technical documentation teams around the globe, are offering a free help site assessment.

They’ll evaluate your self-service help site using the judging criteria from the Codie Awards, which recognizes the best help sites in the industry.

What Is a Help Site Assessment And Why Should You Care?

A help site assessment is like bringing in a brutally honest friend—except this one knows what they’re talking about. It’s a structured evaluation of your self-service help site, focused on real-world usability instead of “Does this feel right?”

What Does A Help Site Assessment Include?

A help site assessment looks at your site through the lens of real users—the people who land there because they have a problem and desperately need answers. Here’s what the assessor evaluates:

• Findability – Can users actually locate the information they need, or does the help site require a treasure map?

• Usability – Is your help site a smooth, intuitive experience, or a digital escape room with no exit?

• Design & Navigation – Does your help site look polished and professional, or does it scream “1998 GeoCities experiment”?

• Search Effectiveness – Does your search bar retrieve useful, relevant results? Or does it serve up a random assortment of documents like a malfunctioning slot machine?

• Content Quality – Is the content helping users, or is it just… there?

Help site assessments should take an objective, expert-driven approach to all of this—because as much as you love your help site, you’re probably too close to see what’s wrong.

Why You (Yes, You) Should Get an Assessment

Look, I get it. You and your team have put in a lot of work. But here’s the deal: your help site is the face of your product after the sale. If it’s bad, users will notice. And then they’ll call support—a lot.

• A clunky help site means longer resolution times, frustrated users, and higher support costs.

• A great help site means happier customers, fewer support tickets, and a reputation for having documentation that helps.

• Most importantly, you can’t fix what you don’t know is broken.

A free, expert assessment gives you an outside perspective and a clear path to improvement—so you’re not just guessing what’s wrong.

What Happens After the Assessment?

After the assessment, you’ll receive:

✅ A full report breaking down what’s working, what’s broken, and what needs immediate attention.

✅ Actionable recommendations—not vague “just improve your UX” feedback, but tangible, practical steps to improve your help site.

No sales pitch, no hidden agenda—just real feedback from experts who know what a great help site looks like.

Ready to Make Your Help Site Less… Helpless?

Your documentation is too essential to leave to chance. And since the folks at Heretto are offering a free assessment, filling out a quick form is the only thing standing between you and a better help site.

It’s time to make your self-service help site award-worthy. Sign up for your free assessment now.

As someone with ADHD, you might occasionally find yourself staring at a sink full of dishes, thinking, I should write a novel, only to end up three hours later knee-deep in a YouTube rabbit hole about how ancient Romans made concrete.

It's not your fault; it's just how your brain throws a party. Enter Large Language Models (LLMs)—AI-powered helpers that might not do the dishes for you, but they can remind you to do them without judgment.

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Why LLMs Are Helpful For Folks With ADHD

In his article, "How Large Language Models Can Assist People with ADHD," Ed Finkler (aka Funkatron) — a passionate advocated for mental health in the tech industry — makes a strong case for why LLMs are a godsend for the easily distracted among us.

These digital assistants don't just provide helpful nudges; they can structure your day, break tasks into bite-sized chunks, and even politely rephrase that borderline-angry email you were about to send your landlord.

They're like the friend who gently pulls you back from the edge—except they're available at 3 a.m. and don't expect you to split the check.

But let's not get carried away. Yank points out that LLMs are not a replacement for your therapist, doctor, or the miracle drug that finally got you to return those overdue 📗 library books. 🤣 They're just here to help you work with your ADHD, not fix it. Think of them as a friendly sous-chef in the kitchen of your life—just don't let them take over the whole recipe.

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Generative AI search engines are here, and they're about to flip the world of technical documentation on its head. These tools won't just tweak how we create, find, or read tech content in the next ten years—they'll completely reshape it.

Let's take a look at what's coming and how it's going to shake things up.

Search That "Gets You"

Generative AI search engines are kicking keyword searches to the curb. Instead of wading through endless links, you'll get straight-up answers that match what you're asking. For this to work, documentation teams must rethink their content—making it clear, bite-sized, and easy for AI to identify, understand, and digest.

Imagine a developer hits an authentication error in API version 2.0. Instead of pulling their hair out while searching, they ask, "How do I fix this error in version 2.0?" Boom—AI answers are delivered on a silver platter, pulled from release notes, FAQs, and code examples. No rabbit holes. No swearing at the screen. Just the right info, right when and where you need it.

The Death Of The Keyboard: The Future Is Conversational

And let’s talk about how all this is changing the way we interact with tech. Generative AI is rewriting the rules for keyboards and typing, making them feel like yesterday's tech.

Why type out awkward, choppy keywords like "fix API error v2" when you can say, "How do I fix this API authentication error in version 2.0?" AI loves a good conversation. It can turn searches into natural, intuitive chats instead of a guessing game with keywords.

Voice input is stepping in as the new favorite.

Why Type When You Can Ask Alexa Or Siri To Figure It Out?

And for the times when typing is still necessary, AI shortens the back-and-forth. It delivers straight answers, so you don't have to refine your search a dozen times. Plus, you can skip typing altogether with multimodal input on the rise. Upload a photo of an error message or tap on predictive suggestions, and AI will deliver the goods.

Sure, keyboards will stick around for professional work or those moments when voice input isn't ideal, but they're no longer the show's star. AI prioritizes ease and efficiency, letting us ditch clunky keyword searches for something that feels human. The future is conversational, and the keyboard is learning to share the spotlight.

Generative AI Search Engines Are Kicking Keyword Searches To The Curb

Early data from Microsoft Bing AI and Google Bard shows people love conversational AI that cuts to the chase with direct answers. Microsoft even bragged that over 100 million people started using Bing daily after they added AI—yes, Bing. Who saw that coming?

Read more

Circle April 7-9, 2025, in bold red marker because San Jose, California, is hosting ConVEx 2025.

This 27th annual confab gathers the sharpest minds in technical documentation, content strategy, content engineering, and content operations. Experts share tips, tricks, and secrets to creating, managing, and delivering better content.

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

The Center for Information-Development Management (CIDM) delivers this annual event, seamlessly blending learning, networking, and inspiration.

Why You Should Be at ConVEx 2025

ConVEx packs a ton into two days. It's not just PowerPoint slides and coffee breaks.

Here's what's in store for attendees:

• Mind-Expanding Presentations: Industry experts will share tips, tricks, and tools you can actually use. Think strategies for tackling your biggest documentation headaches, not boring buzzwords.

• Panel Debates: Join smart people arguing (nicely) about how to fix content chaos, scale operations, and make self-service content less of a hot mess.

• Real-World Stories: Want proof that this stuff works? Case studies will show how top companies beat the odds, streamlined their processes, and made measurable progress.

Browse the Cool Tools Zone

Okay, it's officially called the exhibition area, but let's get real—it's like a candy store for tech doc geeks. Stroll through and check out the latest software, AI tools, and workflow hacks that will save you time, impress your boss, and maybe even make you look like a wizard at work.

Software and service vendors are ready to chat about everything from localization to automation. No awkward sales pitches—just helpful info, product demonstrations, and maybe some tasty chocolates.

Who Should Show Up?

If your job involves creating or managing technical product information or documentation content, this event practically calls your name. It's perfect for:

• Documentation Managers: You're tired of herding cats and need systems that work.

• Technical Writers: Learn tricks to improve your skills and avoid reinventing the wheel.

• Content Strategists: Get ideas for making content people want to use.

• Product Managers: Find out how great content makes customers happier (and your life easier).

• Customer Experience Pros: Find out how great content creates happy, loyal customers who spread the word about your offerings to others.

Why San Jose?

Because Silicon Valley, baby! It's tech central, and San Jose is where innovation, culture, and excellent tacos collide. You'll leave the conference buzzing with ideas—and maybe with a new favorite lunch spot.

Don't Sleep on This

ConVEx 2025 is your chance to meet like-minded pros, swap ideas, and learn from the best. You'll leave smarter, better connected, and armed with solutions to your toughest challenges. Don't miss it!

See the full agenda, speaker lineup, and registration details.

Pro tip: sign up early to lock in your spot. If you act quickly, you can save 10% off the cost of registration when you use discount code — TCW — at checkout.

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Let’s face it: as technical writers, some of us spend a inordinate of time staring at code blocks, inline commands, and system outputs. And when we’re not deciphering the latest JavaScript spaghetti, we’re formatting Markdown in Docs-as-Code workflows that feel like a modern-day version of the myth of Sisyphus.

Enter Monaspace fonts—a new type family that promises to make our lives easier and our documentation more readable.

Before you roll your eyes and mutter, “Another font?” let me explain why Monaspace isn’t just another fancy typeface. It’s a font system designed explicitly for technical content, and it might just make you fall in love with typography. Or at least tolerate it more.

What Are '“Monaspace” Fonts?

Monaspace is the Swiss Army knife of fonts: versatile, practical, and unexpectedly stylish. It’s a family of five distinct fonts—Neon, Argon, Xenon, Radon, and Krypton—each with its personality and purpose.

Think of them as your new best friends in technical writing, with features like seamless style mixing, texture healing (yes, that’s a thing), and metrics consistency.

Monospaced fonts (on the other hand) don’t play nice with others. Each has its own set of rules (metrics), so mixing them can introduce challenges.

Enter Monaspace Fonts — The Peacemakers of the Font World

Designers created monaspace fonts to mix and match without drama.

Want to add more personality to your code? Want to make it easier to process and understand? With monaspace fonts, you can build interfaces that bring order to the chaos and give your code the structure it deserves.

Monaspace empowers writers to juggle code, comments, and prose in the same document.

Why Should You Care?

Monaspace fonts address the common issue of monospaced fonts squishing letters together or spacing them awkwardly by using texture healing. This feature ensures uniform spacing and makes code blocks and inline snippets easier on the eyes.

Monaspace fonts also let you mix and match styles to convey meaning. Comments? Use a handwritten style. Auto-generated text? Try something bold. All without looking like a ransom note.

Monaspace’s flexibility isn’t just for show; the ability to mix styles helps your readers quickly differentiate between types of content, especially when syntax highlighting isn’t available.

Docs-as-Code workflows demand consistency across platforms, and Monaspace delivers. Whether your documentation is a PDF, HTML file, or printed user guide, Monaspace may help you ensure your content looks polished and professional everywhere.

I once thought structured content was the pinnacle of technical writing sophistication. Like labeling all your moving boxes and patting yourself on the back for being organized, I marveled at its clean tags and nested elements, smugly assured that everything was in its place. But just as you can’t solve life’s problems with a color-coded filing cabinet, I’ve come to realize that structured content, while essential, isn’t the whole story.

Welcome to the world of semantic structured content,
where you organize data to make it meaningful.

Structured Content: The Foundation

Structured content organizes information into a predictable framework using markup languages like Extensible Markup Language (XML) or its specialized cousin, the Darwin Information Typing Architecture (DITA). It locks in consistency, makes reuse a breeze, and lets you publish content across platforms and channels.

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Structured content has been a lifesaver for tech writers, rescuing us from the Wild West of unstructured documents and giving us scalable workflows instead of headaches.

But here's the rub: structured content, while fantastic for organizing information, doesn't know what it's talking about. It's like following a recipe exactly but not understanding why baking soda makes the cookies rise. Sure, it's got the structure down, but where's the meaning? Enter semantic content.

Semantic Content: Adding Meaning to Structure

Semantic content, the sophisticated older sibling of structured content, is the key to unlocking a deeper understanding. It doesn't just organize information; it explains what the content means and how it connects to other information. Using technologies like RDF or vocabularies like schema.org, semantic content enriches structured content with context and relationships that machines—and humans—can understand, enlightening readers and enhancing their knowledge.

Think of it like this: structured content is a beautifully organized cookbook written in XML. Semantic content is the same cookbook, but with notes in the metadata that say, "This recipe pairs perfectly with that one," or "Use this ingredient as a substitute in case of dietary restrictions." It's all about adding meaning to the structure, making the content more intelligent and thus more informative.

Here’s another example: a structured content model might include a product name, description, and specifications in a table. Semantic content, however, would go further by explicitly defining relationships, such as "Product X is compatible with Product Y" or "Specification A is required for Feature B." This added layer of meaning allows AI systems to draw inferences, answer nuanced questions, and create contextually-relevant connections that structured content alone cannot.

Why You Need Semantic Structured Content Now

You might think, "This sounds great, but do I need semantic content right now?" The answer is an unequivocal yes. AI and machine learning systems are rapidly becoming central to how people access information, and they thrive on context. They need content that doesn't just say, "Here's some data," but also explains, "Here's why this matters and how it connects to everything else."

For example, structured content can give users detailed specs and instructions if you write product documentation. Semantic content, however, can tell them how features relate, which configurations are compatible, and what scenarios call for specific actions. It helps AI systems answer complex user questions, create personalized recommendations, and support richer user experiences.

Without semantic content, your content is just an instruction manual;
with it, it becomes an intelligent assistant.

So, How Do You Get Started?

Transitioning from structured to semantic content might sound daunting, but it's more manageable than you think. Start by understanding the basics of semantic technologies like Resource Description Framework (RDF), JSON-LD, and Web Ontology Language (OWL).

Look at your content and identify key relationships—what connects to what, and how? Adopt semantic standards like schema.org or industry-specific vocabularies to ensure your content is machine-readable and interoperable.

Most importantly, you should collaborate with your team to weave semantic thinking into your content strategy.

The Natural Evolution of Technical Documentation

The shift from structured to semantic content represents a natural evolution in technical communication. As the demand for smarter systems and personalized user experiences grows, so does the need for content that not only organizes information but also makes it understandable to machines. By embracing semantic content, technical writers can not only meet today’s challenges but also help shape the future of intelligent communication systems.

Now is the time to lead this transformation.

Are you ready to make the shift? 🤠

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Ready to help shape the future of customer self-service? Heretto's groundbreaking research survey is back for its second year, and your voice is more crucial than ever.

The 2025 State of Customer Self-Service Survey goes beyond basic trends – we're uncovering the strategies that turn good support into exceptional customer experiences.

Whether you're crushing it at self-service or just getting started, your insights will help companies across industries unlock their full potential.

By participating, you'll:

• Get early access to industry-defining insights

• Help set new benchmarks for customer support excellence

• Join an exclusive community of forward-thinking professionals

Don't miss your chance to influence how businesses evolve their self-service strategies.

Take the survey!

Interested in the results from our previous survey? Grab your copy of the 2024 State of Customer Self-Service Report today!

The Content Wrangler is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

[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

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?"

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

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?

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?