Impact Of The Right-To-Repair Revolution On Tech Writers

🗓️ November 21, 2024

Explore the changing technical documentation landscape in the wake of groundbreaking right-to-repair legislation with Kyle Wiens, CEO of iFixit. Wiens will unravel how recent legislative victories are reshaping the way documentation is crafted and accessed. Discover how to determine whether you must make your service manuals public, explore the efforts by manufacturers to comply (or not) with these regulations, and understand the terminology challenges that need addressing to maximize the utility of these laws for consumers.

Impact Of The Right-To-Repair Revolution On Tech Writers

🗓️ November 21, 2024

Explore the changing technical documentation landscape in the wake of groundbreaking right-to-repair legislation with Kyle Wiens, CEO of iFixit. Wiens will unravel how recent legislative victories are reshaping the way documentation is crafted and accessed. Discover how to determine whether you must make your service manuals public, explore the efforts by manufacturers to comply (or not) with these regulations, and understand the terminology challenges that need addressing to maximize the utility of these laws for consumers.

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

Personalizing Technical Documentation Experiences

🗓️ November 21, 2024

Kevin Nichols, The Personalization Wrangler, chats with Patrick Bosek, CEO and co-founder of Heretto, about the transformative power of individualized technical documentation experiences. They will discuss how leveraging componentized, semantically rich, intelligent content powers personalization. Learn about role-based access control, preference-based personalization, and permission-based strategies, and gain actionable takeaways.

The Pros and Cons of Adopting Docs-as-Code

🗓️ December 05, 2024

Rachel Lee Nabors, unravels the intricacies of the Docs-as-Code approach to software docs. Discover the advantages and challenges of treating documentation like code. Gain insights into how adopting a systems thinking perspective can significantly enhance your content production capabilities, making your processes more efficient and effective. Walk away with an understanding of the methodology, equipped with knowledge about its benefits and drawbacks.

Content Personalization: 2024 and Beyond

🗓️ December 10, 2024

Kevin Nichols will examine current trends in content production and delivery and assess the impact that AI and other tech advances will have on personalized experiences. Nichols will share insights from a 2024 survey conducted by his firm, AvenueCX (in partnership with The Content Wrangler) and provide a curated overview of the guidance provided by major technology business analysts.

Why “Good Enough” Content Is No Longer Good Enough

🗓️ December 12, 2024

Global content strategy maven Val Swisher will explore how to turn your content into a valuable AI asset, emphasizing the importance of thoughtful curation for effective AI training. She’ll share practical tips for evaluating, cleaning, and organizing content to ensure it’s accurate, relevant, and diverse for AI use.

Putting DITA To Work In The Nuclear Energy Sector

🗓️ January 09, 2024

Explore how the Darwin Information Typing Architecture’s modular content approach is enhancing safety and operational efficiency in the nuclear energy sector with insights from Manfred Hammers of Rivtec, Inc. You’ll learn DITA basics, its role in managing highly regulated documentation, and how it addresses unique nuclear industry challenges by improving content flexibility, safety measures, and cost-effectiveness.

Discovering the Basics of DITA with LearningDITA

🗓️ January 09, 2025

Join Sarah O'Keefe for "Discovering the Basics of DITA with LearningDITA" a free webinar tailored for technical writers who want to learn how to create content in accordance with the Darwin Information Typing Architecture (DITA). Attendees will be introduced to the "LearningDITA" — a free, self-paced, online DITA training course.

Love Your Curmudgeon: Embracing Your Least Likely Partner In Transformation

🗓️ January 21, 2025

Amber Swope from DITA Strategies and Dan Schommer from Intuitive Stack will explore the surprising benefits of having a "workplace curmudgeon" and reveal what drives them. You'll walk away with practical strategies for engaging these team members and turning their resistance into valuable contributions.

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

Heretto’s 2024 report, "From Unsung to Unstoppable: How Technical Writers are Driving the Self-Service Revolution," highlights how technical writers drive the customer self-service movement. The report shows how technical communication is becoming essential for boosting business results, keeping customers happy, and helping organizations succeed.

Key Insights:

1. Changing Landscape: Previously undervalued technical content is considered essential for business success. The report stresses that customer self-service, driven by technical documentation, reshapes industries.

2. Impact on Customer Retention and Career Opportunities: Survey findings reveal that online documentation is heavily utilized when available, significantly impacting customer retention. Many respondents see technical writers’ contributions to self-service initiatives as beneficial to career growth, with 45% believing it can lead to upward mobility.

3. Leadership Support: The report mentions that 90% of leadership supports self-service initiatives, which provide technical writers with a unique opportunity to align their work with business goals and increase visibility.

4. Future Investments: Organizations are committing to further investments in self-service, focusing on technology, content creation, and analytics. This suggests the need for technical writers to evolve their skills, particularly in content strategy, user experience design, and cross-functional collaboration.

5. Recommendations for Technical Writers: The report advises technical writers to:

   • Embrace strategic roles

   • Focus on measurable outcomes like customer retention

   • Collaborate across departments

   • Advocate for recognition

   • Invest in continuous learning and adopt a customer-centric mindset

Request the Report

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

Ever wonder why that 3 p.m. meeting feels like mental quicksand?

Spoiler alert: It’s not just the coffee wearing off—it’s your brain’s way of saying, “I’m out of juice, and you’re asking for a miracle.”

If you’re still scheduling your day like every hour of brainpower is created equal, it’s time for a reality check: Your brain has peak performance times, and your calendar isn’t aware of that.

The Brain's Daily Energy Rollercoaster

Neuroscience has taught us that our cognitive energy is far from constant. Research has shown that the brain's ability to handle complex tasks varies throughout the day, influenced by circadian rhythms and mental fatigue.

Researchers say cognitive performance generally peaks in the mid-morning, declines after lunch, and may experience a secondary, smaller peak in the early evening. This is because our cognitive resources get depleted with each mentally demanding task, a concept referred to as decision fatigue. When we’re low on mental energy, even simple decisions become hard, and complex tasks can feel downright impossible.

For tech writers, whose job demands clear thinking, problem-solving, and creativity, understanding the relationship between brain energy and task performance is crucial.

Pushing through a difficult writing or editing task when energy levels are at their lowest is not just a frustrating experience; it’s a recipe for burnout and subpar work. Unfortunately, many documentation managers overlook this, defaulting to “filling the empty spots on the calendar” as the primary scheduling strategy.

Carla's Story: A Documentation Manager’s Wake-Up Call

Meet Carla, a documentation manager at a mid-sized software company. She was known for her efficient work style, setting up meetings and project milestones with clockwork precision. When she noticed her team’s productivity was dipping and error rates were creeping up, she started digging deeper. What was going wrong?

After chatting with team members, Carla discovered a pattern: people were struggling to complete tasks after attending back-to-back meetings in the early afternoon. The time slots for focused work were filled arbitrarily based on calendar availability, with no consideration for the energy demands of each task. Carla was scheduling tasks and meetings as though all hours were equally productive. She quickly realized that by ignoring the natural ebb and flow of the brain's energy levels, she was making it less likely her team would succeed.

Read more

Let's get real: If your team is drowning in change projects, feeling fed up, and ready to push back, it's not because they're lazy or "resistant." It's likely due to change fatigue—and the 2024 State of Change Fatigue Report breaks down exactly why so many workplaces are spinning their wheels on projects nobody has the energy for.

This new report, by Build Better Change and Mantis Research, didn't just drop stats on the problem; it's packed with solid advice to help you turn this ship around.

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

The Truth Hurts: Key Findings on Why Teams Are Done with Poorly Planned Change

1. Change Fatigue Is Skyrocketing

It turns out all those "special projects" and changes aren't so special anymore. Over 70% of employees say these endless change initiatives are making it impossible to get real work done. More projects are landing on their plates, but leaders are fumbling the planning, leaving employees to juggle everything with less clarity than ever.

2. Planning? What Planning?

Let's be blunt: Only a third of the people in this survey felt their leaders knew how to pick or plan projects that could succeed. Instead, leaders often propose timelines and scopes that are more fantasy than reality, leaving employees to scramble when things inevitably go sideways.

3. Your Team's Burned Out—And Quietly Checking Out

Think burnout isn't a problem? Think again. A whopping 77% of those who face constant change say they're fried. From low morale to lost trust, to full-on "quiet quitting," where people mentally check out, the human cost of this change chaos is hitting hard.

[Get The Book!] CHANGE FATIGUE: Flip Teams From Burnout to Buy-In addresses the foundational psychological safety domains that drive willingness to change, alongside practical change facilitation techniques you can use today, regardless of where your team is starting from.

How to Stop the Madness and Make Change Workable

This report isn't just about pointing fingers; it lays out a straightforward game plan to get change efforts back on track. Here's the gist:

• Vet Projects Like a Boss: Don't green-light every idea because it sounds exciting. Make sure every change initiative aligns with your goals.

• Define Success (Seriously): Spell out what success looks like so your people aren't confused.

• Get Real with Timelines: People are juggling a lot already—don't toss in a surprise deadline that derails their ability to nail everything else on their plate.

• Listen to Your People: They know what's up, so ask for feedback and acknowledge the work they're putting in.

Want Your Team to Buy In? Download This Report

If your teams are tuning out or just flat-out exhausted by all the "big ideas" that never seem to pan out, this report's a must-read. It digs into the real reasons behind change fatigue and offers practical steps to get your team excited about change again—no gimmicks, no-nonsense.

Ready to flip change fatigue into change readiness? Grab the full report and make a difference.

Download The Report

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

Join Patrick Bosek and me for a chat with Kevin Nichols, executive director of experience at AvenueCX. On our January 09, 2025 episode of Coffee and Content , we discuss the future of technical documentation and customer support with groundbreaking insights from a new industry report. 

The Content Wrangler, in collaboration with AvenueCX, surveyed 400 technical documentation professionals to understand how businesses manage and deliver self-service support content. The research explored current trends, technologies, and content strategies shaping customer support's future.

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

We'll explore how self-service documentation is evolving, the role of advanced technologies like AI, XML, and CCMS, and why seamless, omnichannel experiences are becoming critical to both B2B and B2C companies. If you're a technical writer, content strategist, or anyone interested in elevating customer experiences through well-designed support content, this episode is for you. 

Coffee and Content is brought to you by The Content Wrangler and is sponsored by Heretto, a powerful component content management system (CCMS) platform for deploying help and #API documentation in a single portal designed to delight your customers. 

Register

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

The Right to Repair movement is gaining momentum, with new laws and regulations allowing consumers to repair their own devices. Consumers benefit from this revolution, environmentalists rejoice over it, and technical writers feel its impact as well.

Increased Demand for Detailed Repair Manuals

One of the core components of the Right to Repair movement is the availability of repair manuals. As more consumers gain the legal right to repair their devices, there will be a surge in demand for detailed, user-friendly repair documentation.

Technical writers will play a crucial role by creating clear, accurate, and accessible manuals for a broad audience.

Recent Right to Repair Initiatives Around the World

Numerous countries now pass laws, establish regulations, and implement other programs to empower consumers and promote sustainable practices. These actions give significant traction to the global Right to Repair movement. Let's examine recent legislation and how it transforms consumer rights and environmental policies.

United States

• New York’s Digital Fair Repair Act — Manufacturers must provide detailed repair manuals that cover product diagnosis, maintenance, and repair. These manuals should offer clear and complete instructions.
  
  Manufacturers must include safety information in the documentation to ensure users can perform repairs without risking injury or damage. Consumers and independent repair providers should have public access to the repair documentation. This accessibility ensures that anyone attempting a repair can use the same information as authorized service centers. Manufacturers should offer documentation in accessible formats, including digital copies for download from their websites.

  Manufacturers must provide details on diagnostic tools required to repair their products, including instructions on how to use them effectively. The documentation should explain how to obtain and apply any specific software updates or tools necessary for repairs.

  Manufacturers must supply detailed repair and diagnostic information, encompassing service manuals, wiring diagrams, technical service bulletins, and training materials. This information should cover all vehicle systems and components. Independent repair shops and vehicle owners should have access to all repair and diagnostic information on fair and reasonable terms, in both digital and physical formats.

  Photo by Carlos Torres on Unsplash

• Massachusetts: Right to Repair Law for Vehicles — Massachusetts has expanded its vehicle right to repair law to include telematics, ensuring that independent repair shops can access the diagnostic and repair data needed for modern vehicles.

  
  Manufacturers must provide independent repair shops and vehicle owners access to all repair and diagnostic information in digital and physical formats on fair and reasonable terms. They may offer this access through subscription services, ensuring the cost remains reasonable and comparable to what authorized dealers pay.

  Documentation and data-sharing practices must comply with national automotive diagnostics and repair information standards.
  

• California Right to Repair Act — This law mandates that manufacturers of electronic and appliance products make essential repair information and tools available to consumers and independent repair providers.

  
  Manufacturers must provide detailed repair manuals with instructions for diagnosing, maintaining, and repairing their products. These manuals must include step-by-step guides, parts lists, and troubleshooting information. The documentation must include technical diagrams and schematics detailing the internal components and configurations.
  
  Manufacturers must make repair documentation available via their websites or other digital platforms.
  
  Documentation must include comprehensive safety guidelines to prevent injury during repairs. This includes information on handling hazardous components and necessary safety precautions.

  Photo by Flavio

• Colorado: Right to Repair for Farming Equipment In 2023, Colorado became the first state to pass a right-to-repair law covering farming equipment. This legislation ensures farmers can access the necessary tools and information to repair their machinery, promoting agricultural sustainability.
  
  Manufacturers must supply detailed repair manuals that include step-by-step instructions, troubleshooting guides, and maintenance procedures. These manuals should cover all equipment systems and components. Documentation must include detailed technical schematics and diagrams illustrating the equipment's internal workings and component layout.
  

  Manufacturers must make repair documentation publicly accessible so farmers and independent repair shops can obtain the same information as authorized service centers. They should offer documentation through platforms like manufacturer websites or dedicated repair portals.
  

  The documentation must include comprehensive safety guidelines to ensure users conduct repairs safely. These guidelines should cover handling hazardous materials and necessary precautions to avoid injury.
  

• Minnesota: Digital Fair Repair Act — Minnesota joined the Right to Repair movement in 2023 with its Digital Fair Repair Act. This law requires manufacturers to provide parts, tools, and repair documentation for electronic devices sold within the state. This initiative aims to make electronic repairs accessible to consumers and independent shops.
  

  Manufacturers must provide detailed repair manuals covering their products' diagnosis, maintenance, and repair. These manuals should include step-by-step instructions, troubleshooting guides, and part replacement procedures. Documentation must include technical schematics and diagrams illustrating the internal components and device configurations.
  

  Manufacturers must make repair documentation publicly accessible, enabling consumers and independent repair shops to obtain the same information as authorized service providers. They should offer this documentation through digital platforms, such as manufacturer websites or dedicated repair portals.
  

  The documentation must include comprehensive safety guidelines to ensure users can perform repairs safely. It should detail how to handle hazardous materials and outline necessary precautions to prevent injury.

European Union

• EU Ecodesign Regulation — Mandates that manufacturers provide extensive documentation. Manufacturers must supply comprehensive repair and maintenance information to professional repairers and end-users. They must make this documentation available for a minimum of seven to ten years after placing the last unit of the model on the market.
  

  The repair documentation should include detailed instructions for disassembling, repairing, and reassembling the product. It should cover all components essential for the product's function and safety. Manufacturers must ensure professional repairers and consumers can easily access the documentation. They can offer this through online platforms, printed manuals, or other accessible formats.
  

  Manufacturers must provide detailed lists of available spare parts, including part numbers, descriptions, and information on where to obtain them.

  Photo by Revendo on Unsplash

• France: Repairability Index — The index currently covers five categories of electronic products: smartphones, laptops, washing machines, televisions, and lawnmowers. Manufacturers earn a repairability score for each product based on several criteria, including documentation availability, ease of disassembly, spare parts availability, and more.
  
  Manufacturers must provide consumers and professional repairers with comprehensive repair guides and maintenance manuals. This documentation should include:

  • Detailed diagrams and instructions for disassembly and reassembly

  • Information on tools required for repairs

  • Step-by-step troubleshooting guides

  • Safety instructions to prevent injury during repairs

Australia

• Product Stewardship Act — Manufacturers and importers must provide detailed information about the product, including materials used, potential hazards, and disposal instructions. The Product Stewardship Act encourages manufacturers to create and disseminate repair manuals and guides, facilitating product repair by consumers and independent repairers. These materials should include detailed repair instructions, diagrams, and information on the required tools and parts.

  
  The Act also encourages manufacturers to create educational materials, such as guides, brochures, and online resources to inform consumers about the importance of product stewardship, repair, and recycling.

United Kingdom

• UK Right to Repair Regulations — These regulations mandate that manufacturers of certain household appliances must make spare parts and repair information available to consumers and independent repairers for up to ten years after a product's purchase. This aims to extend product lifespans, reduce electronic waste, and promote sustainability.
  

  Manufacturers must provide detailed repair manuals and guides, including step-by-step instructions, diagrams, and lists of required tools and parts.
  

  Manufacturers must ensure easy access to repair documentation, allowing independent repairers and consumers to perform repairs safely and effectively. They must make the documentation clear and comprehensive, providing all necessary information to facilitate repairs.

India

• [Proposed] Right to Repair Law — The proposed Right to Repair Law in India is designed to empower consumers by ensuring they have the ability to repair their own products or access independent repair services.
  
  If the law passes, manufacturers must share manuals, spare parts, and diagnostic tools with consumers and independent repair businesses, making repairs more accessible and affordable.

Shifting Focus From Operational Instructions To In-Depth Repair Information

Traditional technical documentation often focuses on usage and troubleshooting within the confines of warranty and authorized service centers. With Right to Repair, the scope of documentation will expand to include comprehensive repair guides.

Writers must shift their focus from operational instructions to in-depth repair processes, safety precautions, and diagnostic tips.

Collaboration with Engineers and Technicians

Technical writers, engineers, and technicians must collaborate closely to create practical repair manuals. Writers must understand complex technical information and translate it into simple, actionable consumer steps. This collaboration will play a vital role in producing high-quality repair documentation that empowers users to fix their devices.

Embracing New Formats and Technologies

The rise of the Right to Repair movement will likely lead to adopting new documentation formats and technologies. Video tutorials, interactive PDFs, and augmented reality (AR) repair guides could become standard tools for technical writers. Embracing these formats will be essential for meeting the diverse needs of consumers and providing comprehensive repair support.

Ethical and Environmental Considerations

Technical writers must also consider their work's ethical and environmental implications. By contributing to the Right to Repair movement, writers support sustainable practices that reduce electronic waste and promote a circular economy (a systemic approach to longer and more efficient use of resources to avoid waste and resulting pollution). This shift aligns with broader societal goals of environmental responsibility and corporate transparency.

Professional Development and Skills Enhancement

As the demand for repair documentation grows, technical writers must enhance their skills and stay updated with the latest repair techniques and industry standards. To remain competitive and proficient in this evolving field, writers must pursue continuous professional development, attending workshops and obtaining certifications.

Opportunities for Technical Writers

The Right to Repair revolution presents an exciting opportunity for technical writers to expand their expertise and contribute to a significant societal movement. By creating detailed, accessible repair manuals and embracing new technologies, technical writers will play a pivotal role in empowering consumers and promoting sustainable practices.

As this revolution unfolds, the impact on the technical writing field will be profound, offering challenges and rewarding opportunities for those ready to adapt and innovate.

Learn more about the ‘Right To Repair’

Training courses

• iFixit is a leading advocate for the Right to Repair and offers extensive resources, including repair guides and news updates. It also produces iFixit EDU, a project that partners with 98 universities worldwide to teach repair and technical writing.

Survey data

• Consumer Reports survey finds Americans overwhelmingly support the Right to Repair.

Reports

• Public Interest Research Group (PIRG) Right To Repair Reports — The PIRG Right to Repair campaign advocates for legislation to grant consumers and small businesses access to parts, tools, and service information necessary for repairing products. It has seen significant progress with bills introduced or passed in multiple states and has garnered broad public support. The campaign seeks to ensure fair repair opportunities and counteract manufacturer-imposed repair restrictions.

Podcasts

• Repair Radio by iFixit — Apple Podcasts

• Right to Repair Catches the Car — Electronic Freedom Foundation — Apple Podcasts | Spotify

Books

• The Right to Repair: Reclaiming the Things We Own by Aaron Perzanowski explores the movement advocating for consumers' rights to repair their own devices and challenges the restrictions imposed by manufacturers, highlighting the broader implications for ownership, sustainability, and consumer autonomy.

Right to Repair Resources

• The Repair Association — a coalition of businesses and consumers devoted to shaping informed public policy. We are committed to upholding the values of quality repair, engagement and support of consumers as well as businesses, local farmers, and independent repair or service technicians.

• Electronic Freedom Foundation Right To Repair blog

• Repair.org blog

Imagine a virtual world where an incredibly lifelike avatar greets you, ready to deliver knowledge and skills tailored just for you. This isn't a scene from a science fiction movie; it's quickly becoming a reality thanks to cutting-edge technologies that blend artificial intelligence and virtual reality (VR).

At the forefront of this revolution is technology from companies like emerse.ai, which enables organizations to construct robust private training content libraries filled with product information, competitor analysis, industry insights, and general soft skills and methodologies. This treasure trove of data becomes the lifeblood of AI-powered avatars, empowering them to deliver targeted training sessions that are both informative and interactive.

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

Building Knowledgeable Avatars

One compelling use case for AI avatars is training tech writers to understand a product's nuances, enabling them to create better content. In a landscape where accurate and effective communication is crucial, technical writers must grasp the intricacies of the products they document.

Imagine a technical writer engaging with an avatar that functions as a virtual subject matter expert (SME). The avatar can simulate real-world product scenarios accessible through a VR headset or a web browser. The avatar can respond to verbal inquiries about product features, functionality, and use cases, allowing writers to deepen their understanding and create more informed content.

Whether in a virtual reality setting or through a straightforward web interface, these intelligent avatars provide an immersive and informative training experience that adapts to the user's needs.

Immersive training experiences do more than convey information; they actively engage technical writers in a dialogue, prompting them to think critically and apply their knowledge effectively.

The avatar can dynamically generate responses using generative AI based on the latest data from the organization's private content library. This ensures that writers receive accurate and up-to-date information, which in turn helps minimize the occurrence of hallucinations—instances where the AI might generate incorrect or misleading information. Accuracy is critical in maintaining the integrity of the content produced and instilling confidence in the writers' output.

Enhancing Soft Skills Through Simulation

Beyond technical proficiency, AI-powered avatars are instrumental in developing soft skills essential for effective writing and collaboration. Training programs can focus on active listening, constructive feedback techniques, and adapting communication styles, all within a controlled, virtual environment. Technical writers can practice their approach with the avatar, receiving real-time feedback on their writing style and effectiveness.

For example, a technical writer may engage in a role-playing scenario where the avatar, as a virtual SME, provides critical insights and feedback on their drafts. The writer can practice responding to these suggestions, and the avatar can simulate various reactions, providing a safe space for learning and growth. This hands-on experience fosters confidence and equips technical writers with the tools to refine their craft and handle real-life writing challenges more effectively.

The Future of Training is Here

As organizations continue to explore the potential of AI-powered avatars, the implications for training and development are profound. By harnessing the capabilities of generative AI and LLMs, companies can create an engaging and incredibly effective training ecosystem. The ability to build a private content library that informs these avatars means that training can be customized and dynamically updated to reflect the latest product details and industry insights.

In a world where knowledge is power, equipping employees with the right tools to succeed is paramount. Integrating AI-driven avatars into training programs represents a significant leap forward, offering organizations a unique opportunity to enhance their workforce's capabilities. As this technology continues to evolve, the possibilities for immersive training experiences are limitless.

Are you ready to elevate your training processes and leverage the power of AI avatars?

Watch How Artificial Intelligence Drives Soft Skills Training Experiences, a free, one-hour on-demand presentation during which AI software entrepreneur Dominik Wever, CEO and co-founder of Emerse.ai, explores how organizations can harness product information and competitive intelligence to create AI-powered training agents that inform and transform your workforce.

The future of employee training is not just about information—it's about engaging experiences that drive results.

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

Is your self-service customer support portal (help site) performing at its best? Now's your chance to find out—at no cost!

Heretto is offering a free help site assessment exclusively for The Content Wrangler subscribers. They'll evaluate your help site against the Best Knowledge Center judging criteria used by the Software and Information Industry Association (SIIA) in their annual CODiE Awards.

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

The evaluation will highlight your help site's strengths and provide practical suggestions to enhance its effectiveness.

Why should you take advantage of this offer?

Because a well-structured, user-friendly help site can make all the difference in customer satisfaction and support efficiency. Our assessment will give you clear, actionable feedback that you can use to improve navigation, content quality, and overall user experience.

What's included?

• A detailed review of your help site's strengths

• Actionable insights to optimize performance

• Practical recommendations for future improvements

Don't miss out! Take advantage of this exclusive offer to ensure your help site works hard for your customers and you.

Don't let this opportunity slip by. Get your free help site assessment today and stay ahead in delivering top-tier customer support.

Request Free Help Site Assessment

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—selecting a documentation publishing system isn't the most thrilling task in the world. You're probably not eager to dive into spreadsheets full of feature comparisons or sit through hours of vendor demos.

But here's the deal: if you don't specify your requirements clearly before you begin your quest for a documentation publishing system, you're setting yourself up for a world of frustration (and probably more meetings, and no one needs that).

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

This post explains why outlining your needs is the smartest move you can make. Because let's be honest—if you want to avoid future headaches and get something that helps your team meet its business goals, you'll need more than a vague idea of "what looks good in a demo."

Why Specifying Requirements Is Crucial

A documentation publishing system is the backbone of how your team creates, manages, and delivers valuable content that keeps customers happy (and your bosses off your back). Whether you're trying to improve collaboration, automate content updates, or publish to multiple channels, this system has to fit. That's why you must meet your requirements straight.

Why it matters:

Aligning with Business Objectives

Your technical documentation doesn't exist in a vacuum (though it sometimes feels like your to-do list does). It supports everything from product development to customer support. If the system you choose doesn't help your business hit key objectives—like reducing content creation time or improving content quality—then why bother?

By specifying your requirements upfront, you ensure the system you pick is more than just pretty. It'll help your team work smarter, not harder, and no one will argue with that.

Avoiding Feature Overload

Have you ever been in a meeting where someone brings up a super shiny feature that is utterly useless for what you need? Yeah, we've all been there. If you don't outline what's important, you'll get distracted by cool features that don't help you solve your core problems. Or worse, you could obsess over something unrelated to your requirements—like how the UX labels are formatted. Next thing you know, you're fixated on these minor pet peeves that have no real impact on solving your documentation challenges.

Advice: Focus on the essentials, and don't let the small stuff cloud your judgment!

Specifying requirements keeps you focused on what matters—content reuse, workflow automation, assisted authoring, or seamless integrations—so you're not wasting time oohing and aahing over things that won't enhance your team's capabilities.

Ensuring Scalability

Right now, maybe you're managing a handful of documents, but give it a few years (or months), and suddenly, you're drowning in content. If your system can't scale with your needs, congratulations—you've just bought yourself a costly problem.

Thinking ahead—yes, even about things like scalability—means you're setting your team up for long-term success. It's like buying a pair of jeans that actually fit after Thanksgiving—you'll be grateful later.

Facilitating Seamless Integration

Your new documentation system will not live on a lonely island. It'll need to play nice with other tools your team already uses, such as content repositories, terminology and translation management tools, and your customer relationship management system. If your system can't integrate smoothly, get ready for a lot of manual data entry (and no one signed up for that).

Precise integration requirements mean you avoid surprises when your systems cannot communicate, leaving you with more workarounds than you care to handle.

Setting Clear Expectations for Vendors

You know that feeling when you walk into a demo and leave thinking, "Wait, did they even listen to what we need?" Without clearly specified requirements, you'll get vendors showing you their greatest hits—whether or not they apply to your needs.

A crystal-clear set of requirements allows you to steer those demos toward what you need to see, not just what the vendor wants to show off. You can filter out the fluff, so you're not wasting time with platforms that don't cut it.

Getting Started with Requirements Specification

Now that you know this isn't just another hassle, let's discuss how to start. The good news is, it's not complicated (unless you're documenting rocket science).

Engage Your Stakeholders

No one knows your pain points better than your team. Bring in everyone who will use the system—technical writers, software developers, support personnel, IT, product managers, and whoever touches content upstream and downstream. Gather their gripes, hopes, and dreams (okay, maybe just their needs) to build a well-rounded set of requirements.

Prioritize Your Needs

Not all features are created equal. Some are must-haves, and some are nice-to-haves. Sort your requirements accordingly so you don't get caught up in the shiny distractions during vendor pitches.

Think Long-Term

Your team might be small now, but if you don't plan for future growth, you'll outgrow that new system faster than you'd like. Plan for what you'll need down the line—scalability, updates, and ongoing support should all be on your radar.

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

Markdown is a simple markup language that formats plain text easily. It was created to help people write and read documents without needing knowledge of (or experience creating) complex HTML tags or using other markup languages. It relies on basic symbols to add formatting like bold, italics, lists, links, and headers.

For example:

• bold turns into bold.

• italic turns into italic.

• # Header creates a header.

• - List item creates a list.

You save Markdown files with a .md or .markdown extension, and you can convert them into formats like HTML, PDF, or Word.

Because it's easy to use and read, some software developers prefer Markdown for contributing to documentation projects.

Organizations that follow a Docs-as-Code publishing approach usually use Markdown to create content for platforms like GitHub, static site generators, and other documentation tools.

How Does Markdown Differ From Markup Like The Darwin Information Typing Architecture (DITA)?

Markdown and DITA are both markup languages, but they differ in complexity, purpose, and how they're used:

Simplicity vs. Complexity:

• Markdown: Simple and easy to learn, designed for quickly formatting text with basic elements like headings, lists, bold, and italics. It doesn't require users to write complex tags.

• XML DITA: More complex, designed for structured content with rich features like conditional text, topic-based authoring, and metadata. DITA requires a strict tag structure, making it suitable for large-scale, complex documentation.

See related: How to Reuse Structured Content With DITA

Use Case:

• Markdown is ideal for lightweight content, such as blog posts, simple documentation, and notes. It is widely used in version control systems like GitHub for README files and in Docs-as-Code workflows.

• XML DITA: Used for structured, reusable technical documentation, especially in industries that need to manage large volumes of content (e.g., software, manufacturing) or provide individualized content experiences. DITA supports content reuse across different outputs like help files, manuals, and websites.

See related: Make Secure Access a Reality with Personalization

Structure:

• Markdown: It doesn't enforce a specific structure beyond basic formatting, so it's more flexible but lacks advanced content control features.

• XML DITA: Highly structured and modular, with topics (like concepts, tasks, and references) that follow specific guidelines. This structure makes DITA better for managing large, complex content sets.

See related: When To Use The Topic, Concept, and Task Types in DITA

Output Flexibility:

• Markdown: It can be converted into HTML, PDF, or Word, but it offers limited customization without extra tools.

• XML DITA: Designed for omnichannel publishing. DITA content can be transformed into various formats (HTML, PDF, mobile-friendly outputs) while maintaining a consistent look and feel.

See related: Omnichannel or Multi-Channel: What’s the Difference & Can We Use Them Both?

Content Management:

• Markdown: Works well for small teams or individual users but lacks the advanced content management features needed for large-scale operations.

• XML DITA: Supports advanced content management features, including content reuse, version control, and localization, making it ideal for global enterprises with complex documentation needs.

See related: The Quick & Easy Guide to Content Localization

A documentation publishing system is what you need to clean up your documentation mess and turn chaos into order. It's like having a personal assistant helping you create, manage, and publish all those docs without pulling your hair out. Whether you're producing user manuals, product guides, or FAQs, the right system helps get everything out the door without all the drama.

Why You Might Need A New Documentation Publishing System

Your team isn't alone if it's tangled in a content hairball. Most companies hit a point where their documentation pipeline gets so clogged that every new update feels like an epic battle.

You're constantly searching for the correct file, struggling to manage a backlog of change requests, untangling outdated info, and redoing work. A documentation publishing system untangles that hairball and helps you operationalize content production.

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

And let's be honest: If your company hasn't adopted a formal documentation system yet, you probably have one—it's just not likely to be very effective. Maybe you're storing documents in folders on the network, struggling to track down the latest version. Every update becomes a scavenger hunt; managing edits feels like spinning plates. An appropriate publishing system fixes all that.

Types of Documentation Publishing Systems

Component Content Management Systems (CCMS)

Do you have a bunch of content that you reuse? Do you find yourself repeatedly copying content from one document or source and pasting it into another? And when it comes time to update that content, can you remember all the places that you pasted it earlier?

If you're like most of us, you can’t.

A CCMS is the answer. It divides your content into smaller, reusable parts that it stores in one place but displays in multiple locations. Tools like Heretto specialize in this, helping teams manage content across channels and keep things consistent.

Help Authoring Tools (HATs)

If you're creating help documents and knowledge bases, you might find creating and managing your content with a Help Authoring Tool of value. These systems allow you to produce documentation with searchable content and straightforward navigation. Adobe RoboHelp is one big name in this space.

Docs-as-Code Systems

For teams that think like—and collaborate with—software developers, Docs-as-Code systems let you manage your documentation just like software. You'll use plain text, version control, and automation to keep everything up-to-date and in sync. If you like working in Markdown and pushing updates via Git, Docusaurus, or Sphinx might be your jam.

Wiki-Based Systems

When you need different types of contributors to work together on docs, a wiki-based system may be worth a look. These platforms, like Confluence and MediaWiki, let multiple people edit content in real time.

Some fast-moving teams find that wikis are helpful for keeping docs current without causing friction amongst contributors. However, wikis can become more challenging to manage as teams grow or content becomes more complex and fast-paced. Tracking updates, ensuring consistency, and maintaining quality can become overwhelming without stricter controls or more advanced content management features.

Static Site Generators (SSGs)

A Static Site Generator (SSG) might be a good fit for creating a software documentation website where the content doesn't need to change frequently. Some technical documentation teams — often in software start-ups—use these generators to create documentation websites, technical blogs, or product manuals when the content doesn't require frequent updates. The result is a fast, lightweight site that quickly loads because it doesn't rely on a backend to process requests.

However, while SSGs are solid options for relatively stable content, they can be less suitable for documentation that requires frequent updates, as even small changes might require regenerating the entire site.

Tools like Jekyll and Hugo turn your raw content into a fast-loading website. However, you'll need technical skills to set up a website. There are hundreds of static site generators that might work for your purposes.

Is It Time for an Upgrade?

If your documentation process is constantly clogged, you need a better system.

The right documentation publishing system can help you unclog that content hairball, giving you the tools to create, manage, and deliver docs without the headaches.

It's time to ditch your outdated file folder-based content storage system and stop relying on band-aid solutions to overcome publishing hiccups. When your documentation team has the right tools and knows how to use them well, your publishing efficiency will increase, and your stress will drop significantly.

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

Is your team wasting time on labor-intensive tasks like reformatting text, manually managing versions, or struggling to collaborate? Are some of your writers spending more time wrangling with the tech stack than writing content? If this sounds familiar, your publishing system is working against you, not for you.

Watch out for these red flags that signal it's time to switch to a more capable documentation publishing solution.

Your Workflow Is A Hot Mess 🔥

Are you watching your team sink hours into repetitive tasks that a modern system should automate — like reformatting text or manually managing document versions? If collaborating feels like herding cats — with team members stepping on each other's toes to get things done — your system is failing you.

You deserve tools that make the process seamless, not a never-ending hassle.

Your Writers ✍️ Are Mucking Around with the Tech Stack ⌨️

Are your writers turning into part-time system admins, trying to make your tech stack work instead of doing what they do best—writing? If wrangling setups or overcoming technical challenges with tools takes up time they could use to create content, your tools are adding friction.

Your system should enable productivity, not create more problems to solve.

Your Content Looks Like a Patchwork Quilt

If your documentation lacks consistency — with different styles, branding, and terminology popping up from document to document — your publishing system isn't enforcing the standards you need. Inconsistent documentation can confuse users and make your team look scattered.

Your system should help you keep everything clean and uniform so your content speaks with one voice.

Scaling Feels Like a Nightmare 👻

You're in trouble if your docs are growing but your system can't keep up. As you add more content, slowdowns, crashes, or inefficiencies are surefire signs that you've outgrown your current setup and cannot scale. If reusing content across multiple products or channels feels like a Herculean task, you've got a scaling problem.

You need a solution that helps you streamline processes and prepare your organization for growth.

Publishing Across Channels is a Juggling Act 🤹‍♀️

In an omnichannel world, publishing on the web and to PDF, mobile devices, and apps should be effortless. If your team is juggling different tools for different formats or audiences and struggling to keep the content consistent across platforms, your system isn't delivering.

You need a solution that makes omnichannel publishing easy and seamless.

Personalization or Localization is a Pain🧍🏻‍♀️

If your docs feel one-size-fits-all — or localization is an uphill battle — you're not providing the best experience for your users. Personalization and localization shouldn't be a headache; those capabilities should be baked into your system, helping you deliver relevant, localized content without a fuss.

You need a solution capable of helping you deliver individualized experiences, complete with localization.

Version Control is a Constant Struggle 😩

Tracking document versions and managing changes shouldn't feel like solving a mystery. If your team spends too much time chasing down the correct version or tracking approvals, your system isn't up to snuff. Version control should be second nature, not a struggle.

You need a solution that doesn't force you to integrate with external tools to track versions, manage history, or provide an audit trail.

No Analytics or Feedback Means You're Flying Blind 🧑🏻‍🦯

If your publishing system doesn't offer analytics or user feedback options, how do you know if your documentation is hitting the mark? Without this data, you're guessing. That's not a good strategy, no matter how you slice it.

You need a solution that provides relevant insights into how users interact with your docs so you can make evidence-informed decisions for improvements.

Your Tools Don't Talk to Each Other 🗣️

A modern publishing system should integrate easily with the other tools your team relies on that provide the capabilities you need to succeed. If your systems are siloed or you're forced to move data between them manually, your workflow will be clunky and inefficient. Integration is critical to keeping everything running smoothly.

You need a solution that makes it straightforward to connect external tools to your stack.

The System is Slow and Unreliable 🐢

Does your system lag or crash when you need it most? If it's slow or requires constant troubleshooting to keep things moving, it's a clear sign that you need an upgrade.

You need a solution that's reliable, fast, and that doesn't need to be constantly babysat.

Does this sound like you? 🔊

If you recognize these symptoms, stop letting your publishing system hold your team back. The right platform will streamline your workflows, allow your writers to focus on content (not tech wrangling), and make collaboration a breeze. 

Get help understanding your technical documentation publishing system needs today from our friends at AvenueCX!

The annual LavaCon conference, held in Portland, Oregon, from October 27-30, 2024, features an impressive agenda jam-packed with outstanding presenters covering hot topics, new trends, and innovative technologies of interest to content strategy, content development, and technical communication pros.

Can’t make it to Portland? No, problem.

LavaCon has you covered with its Virtual Experience — a live stream of select presentations and access to a library of on-demand recordings of most other sessions for later playback.

Conference Discount: Save 10% off the cost of conference registration using discount code TCW at checkout.

This year's lineup features industry experts such as Val Swisher, CEO of Content Rules, who will present "Why Good Enough Content Is No Longer Good Enough," and Rahel Anne Bailie, a pioneer in content strategy, discussing the future of content operations. Melanie Davis from Reltio will share insights on integrating AI into technical documentation, and Carlos Evia from Virginia Tech will participate on a panel led by Scott Abel, The Content Wrangler, covering the latest advancements in content operations at scale.

Fawn Damitio from Meta and Peggy Sanchez of HPE will present "Metamorphosis: Empowering Our Craft's Evolution in the Dawn of GenAI’s Era," exploring how generative AI is transforming content strategies. Stefan Gentz of Adobe and Kevin White of Workday will discuss "Modernizing Content Strategy: Workday’s Agile Transformation," focusing on agile practices in content management. Meanwhile, Noz Urbina of Urbina Consulting will present "Truth Collapse: The AI Meta-Crisis" will address the complex ethical and practical challenges posed by artificial intelligence in content creation and delivery.

View the complete roster of presenters

It’s more than a learning experience — it’s fun, too!

In addition to the educational sessions, LavaCon offers unique networking and social activities. Attendees can relax with therapy dogs during lunch, join a storytelling night at Kelly’s Olympian, and participate in a karaoke night, complete with a Chinese Dragon Parade​.

Attendees will also enjoy networking opportunities, interactive workshops, and a chance to explore Portland’s vibrant city life. Special activities include a welcome reception and optional city tours to help connect with peers while experiencing the local culture.

Don’t miss this opportunity to learn from the best and take your content strategy to the next level in the beautiful Pacific Northwest!

Conference Discount: Save 10% off the cost of conference registration using 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.

The DOM GraphRAG Project introduces a novel approach to improving retrieval-augmented generation (RAG). It solves the issues with traditional vector-based RAG models by using an improved architecture. This method increases the accuracy, reliability, and context of AI-generated content through the use of Document Object Model (DOM) structures and knowledge graphs.

Related: What is retrieval-augmented generation (RAG)?

Michael Iantosca, Senior Director of Knowledge Platforms and Engineering at Avalara, along with Helmut Nagy, Chief Product Officer, and William Sandri, Data & Knowledge Engineer at Semantic Web Company, wrote the paper to explain the issues with traditional retrieval-augmented generation (RAG), particularly in technical documentation.

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

Problems with traditional vector-based RAG models

Traditional vector-based RAG models have issues that impact their reliability. They can produce inaccurate or misleading information (hallucinations) and lose context.

Vector-based RAG models struggle also with multi-step reasoning and fact-checking, making them unreliable. They typically depend on manual fact-checking, which is both expensive and inefficient. This reliance creates additional challenges because these models can't scale effectively. Their limitations stem from retrieving information based on similarity rather than deeply understanding the content or verifying its accuracy.

While vector-based models are good at retrieving information based on similarity, they're bad at relevance and context. The data they retrieve often lacks the context required for accurate reasoning (as mentioned earlier, fact-checking), leading to misleading conclusions.

And, they cannot easily connect related information across multiple sources, something knowledge graphs are good at.

Adding another negative to the list, vector-based models require a lot of computational power, making them costly to use. The International Energy Agency predicts that AI will use ten times more energy by 2026 than it does today. This increase is due to the rising complexity of AI models and the infrastructure required to support them.

Meet DOM Graph RAG: The smarter way to handle content retrieval

Imagine trying to build a house with a hammer that randomly selects nails based on their color instead of where they need to go. That's pretty much how traditional RAG models handle content retrieval.

Enter DOM Graph RAG — it's like giving that hammer a brain, a blueprint, and maybe even a cup of coffee to ensure everything is done accurately, in context, and with much less chaos!

The DOM Graph RAG model leverages a semantic, content-first approach, integrating neuro-symbolic reasoning and knowledge graphs. By utilizing the DOM to structure content, it preserves the integrity of the original material. This method offers several key advantages over traditional RAG models:

• Preservation of Context: DOM Graph RAG keeps the original content structure intact, essential for accurate content retrieval.

• Neuro-Symbolic Reasoning: This technique combines neural network pattern recognition with symbolic model logical reasoning, enhancing the system's ability to provide factually accurate and logically consistent responses.

• Dynamic Content Management: Unlike traditional vector models that struggle with content currency and relevance, the system efficiently handles dynamic and frequently updated content.

What's In It For Technical Writers?

Technical writers and information developers who create self-service support content can significantly benefit from adopting this model. Traditional RAG models often chunk content arbitrarily, making it difficult for users to find precise, contextually rich information. By contrast, DOM Graph RAG maintains the relationships between topics, elements, and metadata, ensuring users receive accurate, explainable answers to their queries.

For technical writers, the DOM Graph RAG model opens up new possibilities for creating content that is easy to retrieve and retains its context and structure, which is crucial for technical documentation. Furthermore, by automating content updates and managing dynamic metadata, such as entitlement, localization, and version control, DOM Graph RAG can significantly improve the efficiency of content management systems.

[Webinar] October 16, 2024 — DITA-Driven Graph RAG For Customer Self-Service Support

Michael Iantosca, Senior Director of Knowledge Platforms and Engineering at Avalara, and Helmut Nagy, Chief Product Officer at Semantic Web Company, as they unravel the complexities of DITA-powered Graph RAG and demonstrate this innovative solution.

Practical Applications

The DOM Graph RAG model isn't theoretical. It's already in use in chatbot systems, providing more accurate and context-aware responses. By incorporating knowledge graphs and reducing dependence on large language models (LLMs), this approach also reduces computational costs, making it a scalable and cost-effective solution for industries requiring high precision.

The DOM Graph RAG model offers a robust, scalable, and efficient solution that addresses many of the challenges traditional RAG models face. For information developers, adopting this approach can lead to improved self-service support experiences, greater accuracy in content retrieval, and more effective content management overall.

This innovative model is an exciting addition to the literature on AI-driven content management. Take a moment and check out the additional resources available on the Thinking Documentation site.

Download the paper

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

From Unsung to Unstoppable: How Technical Writers are Driving the Self-Service Revolution is a 2024 micro-report by Heretto highlighting technical writers' pivotal role in the customer self-service revolution. The report is based on data collected in the State of Customer Self-Service Survey conducted in 2024. It emphasizes the growing importance of technical communication in improving business outcomes, customer satisfaction, and organizational success.

From Overlooked to Essential

Once the unsung hero quietly collecting digital dust, technical content has finally stepped into the spotlight as a powerhouse for business success. No longer just the 'manual no one reads,' it's now the engine driving customer self-service, reducing support headaches, and boosting satisfaction.

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

As industries increasingly embrace self-service solutions, documentation is no longer just nice to have — it's reshaping how businesses operate and putting technical writers front and center in the quest for innovation and growth.

72% of respondents said well-designed self-service solutions help keep customers around. And 81% mentioned that leadership is finally giving credit to those working on these initiatives. It just goes to show how important technical documentation has become in helping companies hit their goals.

Who knew tech docs could be such a game-changer?

Docs Drive Retention and Open Career Doors for Writers

Survey says: If you build it (well), they will read it!

Online documentation is a hit when it’s easy to find and use, and it’s not just customers who benefit — businesses see a boost in retention, too. In fact, when self-service content is done right, it becomes a major asset.

And here's the kicker: 45% of respondents believe that technical writers who contribute to these initiatives aren’t just helping customers — they’re setting themselves up for a career boost, with plenty of room to climb the ladder.

A Golden Opportunity for Tech Writers to Shine

The report finds that 90% of leaders support self-service initiatives, providing technical writers a unique opportunity to align their work with business goals and increase visibility. With 90% of leadership onboard, it's time for tech writers to grab the spotlight!

Self-service is getting the executive stamp of approval, which means writers have a prime opportunity to crank out content and strategically align their work with business customer experience goals. It's their chance to shine — to step out from behind the scenes and show leadership how their work isn't just helping customers, it's driving success.

Investing in Self-Service: How Tech Writers Must Expand Their Skills for Success

Organizations are doubling down on self-service, pouring resources into technology, content creation, and analytics to keep customers happy and engaged. For technical writers, this means it’s time to step up their game.

Gone are the days of just writing manuals—now it’s about mastering content strategy, user experience design, and collaborating across teams. If tech writers want to keep pace with this self-service wave, they’ll need to become more than just content creators—they’ll need to become content strategists, user advocates, and cross-functional superheroes.

Do yourself a favor and download a free copy of From Unsung to Unstoppable: How Technical Writers are Driving the Self-Service Revolution.

Download Report

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

A collection of advice for improving API Documentation curated from peer reviewed journals, other academic research, and articles written by technical documentation practiontioners.

In the world of product development, identifying usability issues upfront saves time and money and ensures a solid user experience. A recent study in Advances In Human-Computer Interaction explored the effectiveness of a new theoretical method combining Enhanced Cognitive Walkthrough (ECW) and Predictive Use Error Analysis (PUEA) to assess usability issues. The ECW/PUEA approach integrates the evaluation of usability problems and potential use errors within the product development process.

How the ECW/PUEA Method Works

The ECW/PUEA method defines the product, users, and tasks, then describes the system and user interactions. The technique applies ECW to predict user difficulties and PUEA to anticipate errors. The method identifies issues and organizes the results into matrices. This approach gives a clear view of potential problems with usability and safety.

Testing the ECW/PUEA Method with Devs and Students

Students and software development pros tested the method, revealing a mixed bag of strengths and challenges. Although developers appreciated the method's structured approach, which allowed them to identify potential problems and errors systematically, they found it complex, time-consuming, and difficult to learn—especially for those not already familiar with similar usability methods.

Despite the challenges, both groups agreed that the ECW/PUEA method was valuable enough to use again. This consensus reassures us of the method's benefits, suggesting that its value outweighs its drawbacks.

The Role of Team Diversity in Usability Assessments

The study underscored the necessity of team diversity in usability assessments, emphasizing the integral role that each team member plays in the process, making everyone feel included and valued.

Integrating the Method into Development Workflows

As product developers continue to seek ways to improve usability assessments, this new method offers a promising, though complex, tool that could help teams identify issues before they become costly problems.

By examining this new approach's strengths and challenges, developers and usability experts can better understand how to incorporate it into their workflows. This understanding helps them create more user-friendly products right from the start.

Scenario-based writing is a strategy that utilizes real-life situations and narratives to engage people. By adding real-life scenarios to documentation libraries, teams can create more engaging, relatable, and compelling content for users. This approach to writing helps people find answers to their questions that arise during real-world situations.

How Scenario-Based Writing Helps Improve AI Results

Incorporating scenario-based content into a product's technical documentation portal can significantly enhance the effectiveness of generative AI tools in addressing "why" and "what" type questions.

Scenario-based writing enhances the self-service content experiences increasingly provided by technical documentation teams. Infusing real-life scenarios into documentation libraries makes the self-service experience more engaging, relatable, and compelling.

Scenario-based content provides context for users to understand a product's practical applications. Incorporating this content into a documentation library enables generative AI to generate more relevant and insightful responses. By understanding the context in which a product is used, the AI can better address questions about its purpose and functionality.

Why How-To Content Is Not Enough

Large language models (LLMs) like OpenAI's GPT-4o generate human-like responses. Their effectiveness relies on the quality and comprehensiveness of their training data.

Traditional technical documentation—such as step-by-step procedures, reference data, tutorials, onboarding instructions, and quick-start guides—lacks the contextual depth needed to deliver the types of complex "what if” and “why” or "why not" answers users seek. This gap can cause LLMs to produce incomplete or speculative responses, a problem known as hallucination.

The Role of Scenario-Based Content

Scenario-based documentation fills this gap with rich, contextual narratives beyond procedural instructions. It explains the reasoning behind features, design choices, and operational constraints.

Incorporating scenario-based documentation allows LLMs to access a broader, more nuanced dataset, enabling more accurate and relevant answers that address specific user needs and challenges that standard how-to guides usually do not cover.

Incorporating this scenario-based product content into a unified product documentation library helps LLMs better understand the reasons behind user inquiries. For example, when a user asks "why not" use a particular feature, the AI can use scenario-based examples to explain potential limitations or suggest alternative solutions that fit user needs.