The Underdog of Learning Resources

The 2025 Developer Survey paints an interesting picture. You’ve got your standard array of learning tools — Stack Overflow, blogs, online courses, and of course, videos. But lurking quietly in the background, capturing the attention of a staggering 68% of respondents, is technical documentation. It’s the often underappreciated rock star in a world obsessed with quick fixes and instant gratification.

Let’s break it down. Of the 33,454 developers who were polled (76% of them being the true “professional” variety and an additional 15% falling into the aspirational or adjacent developer category) there was a strong consensus. You need technical documentation to learn how to code. Let that sink in.

It’s clear we tech writers are holding the reins of knowledge, quietly helping software developers avoid the chaos of poorly understood libraries and buggy frameworks.

The Developer’s Best Friend: Technical Documentation

Now, we all know that developers have a way of loving their code more than they love life itself. 😆 Still, these same developers (mostly aged between 25 and 44) are relying on our docs to make sense of their tools, libraries, and frameworks. There’s a good reason why a significant 68% of survey respondents preferred it over other resources. It’s simple. It works.

While Stack Overflow answers might solve an immediate issue, they don’t explain why things work the way they do (and even when they do, there’s no guarantee it'‘s accurate). Enter technical documentation (the unsung hero of the coding world). Developers, especially those with less than 10 years under their belts, might not be able to remember every edge case for every function call, but the doc we produce help them get it when it matters most.

It’s the difference between frantically Googling “why does my program crash every time I try to run it?” and confidently consulting well-organized reference material that tells you what you’re doing wrong and how to fix it. It’s like the difference between using a map and wandering aimlessly.

Why Documentation Is the Bedrock of Success

Okay, I’ll admit that documentation isn’t exactly the glamorous, party-loving cousin of a slick YouTube tutorial or a rapid-fire Stack Overflow answer, but it is where foundational knowledge lives. For most developers, especially those in the 35% who have been coding for fewer than 10 years, learning to code with solid documentation means building a robust, scalable understanding that no quick fix or trendy blog post can replace.

The Case for Appreciating Technical Writers

So, dear tech writers, it’s time we stand tall and claim our rightful spot at the table of essential resources. Developers might use other tools for a quick fix, but when it’s time to dive deep into understanding and mastering a framework, they’re coming to us. Documentation isn’t just a reference; it’s the bedrock of their continuing success.

And to all the developers reading this: Next time you’re diving into a technical topic, remember that the person behind those docs aren’t just throwing a bunch of words into a file. They’re saving your proverbial butt one detailed, well-organized, thoroughly tested section at a time. And in a world where most things come with a “don’t ask, just Google it” disclaimer, isn’t that worth a little appreciation? 🤠

That should sound familiar, because tech writers are supposed to care about exactly those things — and more.

A system may be logically designed. A workflow may be technically correct. A product team may insist the interface is “clear.” Meanwhile, the user is staring at a screen wondering whether clicking Save will publish the document, overwrite the document, summon legal, or end civilization as we know it. Phenomenology asks us to take that user experience seriously.

We need phenomenology because documentation is not just about describing how a system works from the inside. It is about helping someone navigate how that system appears from the outside, in real conditions, with limited context, imperfect memory, and a growing suspicion that every button has been named by a committee with boundary issues.

This matters because users do not experience products as architecture diagrams. They experience them as moments: confusion, hesitation, recovery, success, error, relief. Good documentation meets them there. It anticipates where they are likely to get lost, what they are likely to misread, and what they need in order to move forward with confidence.

In practical terms, phenomenology reminds us to pay attention to the user’s point of view, not just the system’s logic. It encourages us to write for the reality of use, not the fantasy of design. And that is important, because a procedure is only “clear” if it is clear to the person trying to follow it while three deadlines, two warnings, and one expired permission token are breathing down their neck.

Good documentation does not just explain the product. It respects the experience of using it. That is why phenomenology matters. 🤠

That may sound like philosophy-class material best left to people wearing scarves and speaking in paragraphs no one asked for. But tech writers deal with epistemology all the time.

Every time we ask a subject matter expert to verify a procedure, question whether two sources conflict, decide which version of the truth belongs in the manual, or try to separate official guidance from tribal folklore, we’re doing epistemic work. We’re not just writing things down; we’re evaluating claims, testing evidence, identifying authority, and deciding what the reader should be able to trust.

That matters even more now that AI systems increasingly consume and remix documentation. If the source content is vague, inconsistent, poorly governed, or based on undocumented assumptions, the machine may produce fluent nonsense with the confidence of a man explaining wine in a restaurant. Epistemology helps writers think more clearly about provenance, evidence, certainty, and trust.

In practical terms, tech writers need epistemology because documentation is not just about expressing knowledge. It is about deciding what knowledge deserves to be expressed, how firmly it can be stated, and what supports the claim. In other words, good documentation does not just tell users what is true. It helps ensure the truth has not been assembled from guesswork, vibes, and somebody’s half-remembered Slack message.

A strong documentation practice is, in part, a disciplined way of knowing. That is why epistemology belongs in the conversation. 🤠

That is why Women in Technical Communication: From Typewriters to Touchscreens: a history by the women who did the work, edited by Sharon Burton, deserves a place on every technical writer’s reading list.

This anthology brings together firsthand stories from women who helped shape the profession across more than fifty years of change. From typewriters to PCs to smartphones, these contributors did not merely observe the field evolving. They built careers in it, influenced it, and in many cases helped define it. Which is more than can be said for the occasional modern pundit who has been in the field for eleven minutes and is already announcing its complete reinvention. 😆

What makes this book valuable is that it preserves the voices of the women who did the work

Not the sanitized corporate version. Not the after-the-fact summary. Their own words. Their own experiences. Their own accounts of building careers, leading change, and making space for themselves in workplaces that were not always eager to make room.

Technical communicators document everything except their own history. We preserve processes, systems, and product knowledge with almost religious devotion, but somehow leave the story of our own profession sitting unlabeled in a cardboard box. This book helps fix that.

Buy The Book!

It also offers perspective at exactly the right time! As tech writers wrestle with AI, automation, and yet another round of people insisting the profession must now become something entirely new, this anthology reminds us that change is not new. Reinvention is not new. The need to adapt without losing the plot is not new.

Newer technical writers should read this book to understand the roots of the profession. Experienced practitioners should read it for recognition and context. Leaders should read it because professions are built by people over time, not by tools, hype, or somebody’s aggressively branded framework.

If you care about technical communication as a discipline, not just a job title, buy this book. Read it because the field needs memory. Read it because the women who helped build it deserve to be heard. Read it because a profession that forgets its own history is doomed to keep rediscovering itself like a man who loses his glasses while wearing them.

Women in Technical Communication, edited by Sharon Burton, is published by XML Press. Release date: March 30, 2026. Paperback: US $45.95. Ebook: US $29.95.

Contributors List

An ontology sits above all of them.

If AI systems are now reading, interpreting, and speaking on behalf of our documentation, understanding what an ontology is—and what it is not—becomes essential.

A Plain-Language Definition of Ontology

In the context of technical documentation:

An ontology is a formal model that defines what things exist in our domain, what they mean, and how they are allowed to relate to one another.

It does not store content. It does not store prose. It defines meaning and rules.

Why “Meaning” Matters More Than Ever

Traditional doc systems assume a human reader. Humans infer meaning from context, tolerate inconsistency, and notice when something feels “off”.

AI systems do none of that reliably. They need meaning to be explicit, not implied; exactly what an ontology provides.

What An Ontology Actually Contains

In technical documentation, an ontology typically defines four things.

1. Concepts

The things that exist in your product and documentation universe.

Examples:

• Product

• Product version

• Feature

• Component

• Task

• Configuration

• Warning

• Error message

• API endpoint

• User role

An ontology answers: “What kinds of things are we allowed to talk about?”

2. Relationships

How those concepts connect to each other.

Examples:

• Feature is part of Product

• Task configures Feature

• Warning applies to Task

• Feature is deprecated in Version

An ontology answers: “How are these things allowed to relate?”

3. Constraints

Rules that prevent invalid combinations.

Examples:

• This feature only applies to certain product versions

• This task is only valid for admin users

• This configuration is incompatible with another feature

• This warning must appear whenever a specific condition exists

An ontology answers: “What must never be combined or inferred incorrectly?”

4. Terminology control

Shared understanding of language.

Examples:

• Preferred terms vs. synonyms

• Deprecated terms

• Acronyms and expansions

An ontology answers: “When we say a word, what do we mean—and what do we not mean?”

Ontology vs. Taxonomy vs. Metadata

These are related, but not interchangeable.

Taxonomy

A taxonomy organizes things into hierarchies.

Example:

• Product

  • Feature

    • Sub-feature

Taxonomies answer: “How do we group things?”

Metadata

Metadata describes individual content objects.

Example:

• Product = X

• Version = 4.2

• Audience = Admin

Metadata answers: “What attributes does this piece of content have?”

Ontology

An ontology defines the rules behind both.

It answers:

• What counts as a Product?

• What is the difference between a Feature and a Configuration?

• Can a Task apply to multiple Products?

• When is something invalid, deprecated, or incompatible?

Without an ontology:

• Taxonomies drift

• Metadata becomes inconsistent

• AI systems guess

Why Ontologies Matter Specifically For Technical Documentation

1. They prevent concept drift

Over time, teams start using the same word to mean different things.

Ontologies force alignment:

• A feature is not a task

• A task is not a concept

• A version boundary is real, not optional

This clarity improves both human comprehension and AI accuracy.

2. They enable trustworthy AI answers

AI systems that rely on documentation increasingly use semantic retrieval and generation.

Without an ontology:

• AI retrieves text that sounds relevant

• Answers may combine incompatible concepts

With an ontology:

• AI retrieves content that is conceptually valid

• Constraints prevent nonsense answers

This is the foundation of ontology-grounded RAG.

3. They elevate the role of technical writers

Ontologies surface a truth many organizations ignore:

Documentation is not just content. It is a knowledge system.

Technical writers are uniquely qualified to:

• Define concepts clearly

• Establish boundaries and intent

• Model relationships humans understand intuitively

Ontologies make that expertise visible and strategic.

See also: What Is Ontology-Grounded Retrieval-Augmented Generation?

What An Ontology Is Not

An ontology is not:

• A style guide

• A glossary (though it may reference one)

• A CMS configuration

• A single diagram created once and forgotten

An ontology is a living semantic contract between:

• Content

• Tools

• AI systems

• Humans

When Do You Need An Ontology?

You especially need an ontology if:

• Your products are modular or platform-based

• You support multiple versions simultaneously

• You are building or buying AI assistants

• Your documentation feeds chatbots or copilots

• Consistency and trust matter

If AI is now the front door to our documentation, an ontology is the lock that keeps the wrong answers out.

The Takeaway For Tech Writers

In technical documentation, an ontology answers the hardest question of all:

“What does this actually mean — and what is it allowed to mean?”

Writers who help define and govern ontologies shape how:

• Content is retrieved

• Answers are generated

• Products are understood

As AI becomes the voice of your documentation, ontologies decide whether that voice is informed — or improvising.

And improvisation is not a strategy. 🤠

If you remember nothing else, remember this: DITA topics exist to do one thing for one user intent — clearly, consistently, and reuse-ready. 🧐

That single idea explains why DITA works so well at scale and why it behaves differently from traditional document-centric authoring.

See also: What is the Darwin Information Typing Architecture (DITA)?

What Makes a Topic a Good Topic?

A DITA topic is effective when it meets these criteria:

• Single intent — It answers one question or supports one task

• Self-contained — It makes sense without relying on surrounding prose

• Context-aware — Metadata defines product, version, audience, and conditions of use

• Reusable by design — It can appear in multiple documents without rewriting

If a piece of content reads awkward when reused, it probably wasn’t written as a true topic.

Why DITA Topics Exist

Before DITA, most technical documentation followed a document (book) model:

• Long manuals

• Linear chapters

• Content written once, reused by copy-paste

• Updates scattered across multiple files

That model breaks down when you need to:

• Reuse content across products and versions

• Publish to multiple outputs (PDF, web, help systems, chatbots)

• Keep information accurate over time

• Support automation, search, and AI

DITA flips the model. Instead of starting with a document, you start with topics.

The Three Core Types of DITA Topics

Most DITA implementations rely on three foundational topic types. Each enforces intent.

1. Concept Topics — “What is this?”

Concept topics explain ideas, principles, or background information.

Examples:

• What a feature does

• Why a setting exists

• How a system behaves

They help users understand before they act.

2. Task Topics — “How do I do this?”

Task topics walk users through steps to complete a goal.

Characteristics:

• Clear goal

• Prerequisites

• Ordered steps

• Expected results

They answer action-oriented questions and work especially well for procedural content and automation.

3. Reference Topics — “What are the details?”

Reference topics provide structured facts.

Examples:

• Parameters

• Commands

• Error codes

• Field definitions

They prioritize accuracy, consistency, and scannability over narrative flow. 🤠

DITA matters because it forces clarity and discipline at the point of creation. Each topic has a single intent — concept, task, or reference — which makes content easier for people to scan and easier for machines to process. That structure enables reliable reuse, reduces duplication, and improves consistency across products, versions, and channels. Writers stop rewriting the same explanation five times and start managing one trusted source of truth.

DITA is also built for scale and change. Its specialization and inheritance model lets organizations extend the standard without breaking it, while maps assemble topics into many deliverables from the same content set. The result is faster updates, cleaner localization workflows, and publishing pipelines that can target PDFs, HTML, portals, and help systems from the same content base.

Finally, DITA future-proofs documentation for AI-driven delivery. Because topics are semantically typed and structurally consistent, search engines, chat systems, and retrieval-augmented generation pipelines can identify intent and return precise answers instead of dumping entire pages. In an era where documentation feeds intelligent systems, DITA gives technical writers a way to make content both human-readable and machine-ready.

DITA content is best managed in a component content management system designed specifically to help technical writers create, manage, and deliver documentation to the humans and machines that require it. 🤠

A DITA topic is a small, self-contained unit of information designed to answer one specific user need. Not a chapter. Not a document. Not a dumping ground for everything related to a feature. One purpose. One job.

A DITA topic has three defining characteristics

1. It has clear intent

Every DITA topic exists to do exactly one thing: explain a concept, describe a task, or provide reference information. This is not an accident. DITA enforces intent through information typing—most commonly concept, task, and reference.

Related: Understanding DITA Topic Structure

That constraint forces writers to decide why the content exists before writing it. Is the user trying to understand something? Do something? Look something up?

📌 If you cannot answer that question, you do not yet have a topic.

This is one of the reasons DITA content works so well with search, delivery platforms, and AI systems. Intent is explicit, not implied.

2. It Stands on Its Own

A DITA topic is designed to be meaningful outside the context of a book or manual. Someone might encounter it through search, a chatbot, an embedded help panel, or an AI answer engine. Regardless of how they encounter it the topic must still make sense.

That means no “as described above,” no unexplained acronyms, and no reliance on surrounding pages or section headers to fill in critical gaps. Context travels with the topic through metadata, structure, and reuse — not through proximity.

This independence is what enables reuse at scale without copy-and-paste chaos.

3. It’s Structurally Predictable

A DITA topic follows a consistent structural pattern: a title, a body, and clearly defined elements inside. Tasks have steps. References have tables and properties. Concepts explain ideas, not procedures.

That predictability is not just for writers; it is for machines (computers, specifically). Structured topics allow systems to classify, filter, assemble, personalize, and deliver content dynamically. This is why DITA topics are increasingly valuable in AI-driven environments.

Large language models do not “understand” documents. They perform far better with small, well-typed, semantically clear units of information.

Why This Matters Now

As search engines turn into answer engines and documentation gets consumed in fragments, the DITA topic becomes the atomic unit of knowledge delivery. Writers who understand how to design strong topics are not just explaining products; they are engineering intent-aware, machine-processable content that feeds knowledge systems.

If you want AI solutions to give users the right answer instead of a plausible one, start with better topics.

If your content:

• clearly states its purpose,

• uses consistent information types,

• exposes relationships through structure and metadata,

AI can reason over it. If it doesn’t, AI guesses.

Structured, semantically augmented DITA content allows AI systems to:

• distinguish learning intent from execution intent,

• select the right topic type for the moment,

• avoid blending procedural steps into conceptual explanations,

• reduce hallucination caused by context collapse.

In short, it helps AI choose instead of invent.

What This Means For Tech Writing

Technical writers are no longer just explaining products. They are designing intent-aware knowledge systems.

Every time you:

• choose a topic type,

• enforce information typing discipline,

• add meaningful metadata,

• break monolithic docs into purpose-driven components,

you make it easier for AI search engines to deliver the right answer, not just an answer.

In an AI search world, visibility depends less on keywords and more on whether machines can understand what your content is for.

DITA doesn’t just support that future. It anticipates it. 🤠

As a technical writer, I can’t help but laugh. Not because it isn’t serious—it is—but because most of us know the dirty little secret: the hardest part of this job has never been “writing words.” If it were, we’d have been replaced long ago by marketing interns with liberal arts degrees and a case of LaCroix. The real challenge is making sense of a world where nothing stays still long enough to document it.

Enter generative AI, the latest character in our tragicomic office play.

According to McKinsey, it’s going to “enable the organization of the future”. That’s consultant-speak for “brace yourselves, everything is changing again.” But if you read past the buzzwords, there’s an important caveat: organizations may be powered by gen AI, but they’ll still be driven by people. People like us — the ones who are supposed to explain this circus to everyone else without sounding like lunatics.

I’ve already watched AI crank out draft documentation that looked eerily plausible. For about ten minutes, I felt my job security wobble.

Then I read it again. It was like watching a magician pull a rabbit out of a hat, only to realize the rabbit is taxidermied and missing an ear. Sure, it looked like documentation, but it was riddled with hallucinations, half-truths, and the kind of optimism usually reserved for timeshare salesmen.

Researchers have pointed out that “hallucinations” are one of gen AI’s most persistent flaws. That’s when it hit me: the AI can spin a story, but it can’t tell when the story is useful — or true. That part is still mine to do.

What does this all mean?

What this means is that our work is changing shape. We’re no longer just scribes capturing the output of developers. We’re now interpreters of machine output, risk translators, and—if we’re honest—therapists for colleagues who are quietly terrified that a chatbot is going to replace them.

AI may draft the words, but we’re the ones who make sure those words don’t cause a lawsuit, a meltdown, or a late-night call from a panicked customer who followed the wrong instructions.

McKinsey says the organizations that thrive will be the ones that embrace experimentation, trust, and adaptability.

That sounds lofty, but in practice it looks a lot like what tech writers already do:

• experiment with tools

• figure out where they break

• and then explain it to everyone else using metaphors that involve cooking or IKEA furniture

We’re professional sense-makers in a world that makes less and less sense.

So, yes, gen AI is here to stay. It will keep generating, and people will keep being people — messy, skeptical, hopeful. And technical writers will be the ones stitching those two realities together, half comedian, half cartographer. In the “organization of the future,” that’s a job description AI can’t fake. 🤠

And then, the existential question hits: Could a robot do this?

According to the latest report by the Society for Human Resource Management (SHRM), business, finance, and HR jobs are the most likely to face the automation axe. But technical writers? We're not even on the list of highly at-risk jobs. (😮‍💨 Cue a cautious sigh of relief.)

Now, before you get too cozy, let's talk about why. AI tools can efficiently generate introductory text and automate formatting tasks, but they struggle to handle the nuance of technical writing. That's because technical writing involves more than slapping words on a page.

It requires its practitioners to wrangle complex concepts into something accurate and digestible, while anticipating the confusion of users who may not know an API from their elbow.

AI may help with routine tasks—generating tables, auto-summarizing, or suggesting simpler phrasing—but it just doesn't cut it when it comes to making sense of a feature held together by duct tape and hope or translating developer shorthand into something that won't make users cry.

So, while automation might take a bite out of some industries, technical writing—at least involving critical thinking, creativity, and plain old human intuition—still needs people. We're not just typists. We're sense-makers, storytellers, and those who can spot when a spec is about to send the entire project sideways.

This period is especially interesting because it includes the PC revolution through the dot com boom through the birth of the internet as the everyday world, available on smartphones in nearly every corner of the world. Additionally, the field changed from predominately male to predominately female.

Technical communication industry veteran and university instructor, Sharon Burton, is looking to capture the stories of women working in the field.

Interested in participating? Respond to the Call for Writers.

• Maybe you ditched the endless chaos of sticky notes and random file names and finally figured out how to get your act together.

• Perhaps you leveled up your info-management game to the point where your team runs like a German train schedule—efficient, precise, and oddly satisfying.

• Or maybe — just maybe — you’ve cracked the elusive code on tracking metrics that mean something—no more pretending that page views alone are changing the world.

Whatever your situation, you probably have a valuable story with lessons learned to share with others. If that’s the case, I’d like to hear from you.

I’m working to fill our webinar schedule with stories from practitioners working in the trenches. If you’d like to share your story, complete this short form. I’ll get back to you shortly to schedule a call to discuss the opportunity.

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).

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.

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.

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.

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.

Listen To Podcast

What does a README file contain?

Here's a breakdown of what you might expect to find in a typical README file:

1. Project Title: The name of the project

2. Description: A brief overview of what the project does

3. Installation Instructions: Steps required to install and set up the software

4. Usage: Examples of how to use the software

5. Contributing: Guidelines for contributing to the project

6. License: Information about the project's license

7. Authors or Acknowledgments: Credits to project contributors

8. Contact Information: How to get in touch with the maintainers

What to Include in your README

Hillary Nyakundi suggests you consider including these ten things in a README file:

Where are README files stored?

README files are typically stored in the top-level directory of the project. This is where someone new to your project will likely start. Code hosting services like GitHub, Bitbucket, and GitLab will display the README alongside the list of files and directories in your project. 

README Examples

• TensorFlow is an open-source machine learning framework by Google. Their README file provides a comprehensive overview, installation instructions, and links to further resources.

• React is a JavaScript library for building user interfaces, maintained by Facebook. The README includes a brief description, installation instructions, and links to documentation.

• Vue.js is a progressive JavaScript framework. Its README file gives an introduction, installation steps, and links to the documentation.

• Django is a high-level Python web framework. The README provides an overview, installation guide, and contribution instructions.

A seasoned content expert and polymath, Gilhooly's expertise spans the complexities of generating, managing, and delivering technical documentation at scale. Her background includes working with software vendors that develop tools for content teams and leading strategies for innovative content creation groups that produce complex technical product information. Recently, Gilhooly's team was a finalist in the Software Industry Information Industry Association's 38th annual 2023 CODiE Awards in the Best Knowledge Center/Help Site category.

The Interview

Scott: Before diving into the details surrounding the unified self-help portal you've built at Reltio, tell our audience about yourself and the experiences that have shaped how you think about content.

Megan: Hey, Scott! So lovely to have a new label - "Content Polymath." Love it!

I've been in content my entire career, starting as a print journalist before websites were a thing. I went into technical writing and grew my career from an individual contributor upwards, and I've worked in all sizes of companies, from 12-person start-ups to Amazon. Every one of those roles inspired how I think about content delivery and content consumption.

Amazon influenced me as a leader, although our content delivery mechanisms were surprisingly archaic on my teams. There was a big appetite for innovation, so being there helped me think about what we could do for customers.

Scott: You've been an advocate for — and a practitioner of — evidence-informed change. What evidence did you collect to help inform your change-related decisions at Reltio? Provide an example.

Megan: I love the idea of evidence-informed change — keeping history visible in the rearview mirror to guide you while not allowing it to hold you back. I'm also a big believer in solving the problems that matter and prioritizing problems over promises.

What I mean by this is find the 1-3 issues that are critical to your team's (or company's) success, and then focus on solving those rather than thinking about your favorite software tool and advocating for it using a laundry list of promises you believe the tool could help you keep.

Here's an example from my time at Reltio where I prioritized issues.

We had a home-grown documentation portal and no taxonomy. We stored content in a software code repository. Our India team worked through the night every Wednesday to publish content. Not to create and review content but to publish it (something that should have taken minutes, not overnight).

Our process efficiency relied on humans behaving predictably and making no mistakes. We designed our process around tools, not content. And we were using software tools designed for purposes other than creating and managing technical content.

While those obstacles were challenges, they were also opportunities to create a better content experience. Solving our publishing problem allowed us to select fit-for-purpose software. Investing in the tech stack also provided us with opportunities to overcome additional challenges.

More importantly, when I presented the C-suite with data showing how and why our writers worked overnight, no one questioned whether or not we had a problem worth solving. Reltio cares about its employees, so it was a straightforward decision.

Scott: Describe the workflow used by Reltio to produce docs before making changes in the content production approach. And talk about the challenges those processes introduced.

Megan: The team had an impressive workflow. They had processes documented, and they followed them to the best of their ability. We relied on manual intervention while attempting to navigate a less-than-optimal tech stack. The team got requests via JIRA, wrote in Google Docs, went back and forth between subject-matter experts (SMEs), and then transferred the final draft content to XML using Oxygen. We stored our docs in BitBucket, a Git repository for software developers, and then moved them into our home-grown portal.

One of our biggest challenges was updating content.

Writers had to navigate a series of time-consuming manual tasks, jumping in and out of multiple software tools to create and deliver technical information. Writers and SMEs found the productivity-zapping experience frustrating and error-prone.

Read more

Related: The EU Artificial Intelligence Act

For tech doc pros, this means expanding the scope of documentation to include AI functionalities, decision-making processes, data practices, and privacy and bias mitigation measures.

Register

Can’t make it? Register, and we’ll send you a link you can use to watch a recording when it’s convenient 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 to deploy help and API documentation in a single portal designed to delight your customers.

Join Mark Hellinger, Co-founder of Videate, and Jarod Sickler, Senior Solutions Consultant at Heretto, as they unveil how this innovative approach revolutionizes video training and documentation creation. In this informative one-hour presentation, you'll learn how to transform text-based documentation into engaging video content effortlessly.

You'll also hear some eye-opening results from the State of SaaS Customer Success and Product Training Videos Report, revealing why 60% of companies see video as the key to self-service support and how 93% believe it's crucial for customer acquisition and retention.

Moreover, we'll discuss how the Videate browser plug-in for Heretto can help you produce multilingual video documentation affordably and at scale. You'll learn how early adopters enjoy significant cost savings from automatically generating video tutorials from source XML DITA content.

Don't miss out on these insights that could redefine your content strategy and enhance your customer experience.

Can't make it? Register, and we'll send you a link to watch a recording when convenient.

This web presentation is brought to you by The Content Wrangler and sponsored by Heretto, a powerful component content management system (CCMS) to deploy help and interactive API docs in a single portal designed to delight your customers.