It’s time we talk about customer experience. No, not the "smile-and-nod" kind you give your barista when they remember your name. I'm talking about the full-blown, Broadway-production-level experience companies try to orchestrate from first click to final sigh of satisfaction.

The understudy carrying the whole show? It's your content! Yes, your dusty ol' documentation, your FAQs, your user guides, and your troubleshooting trees that look like a caffeinated spider drew them.

A recent literature review by Muhammad Waqas and friends found that the customer experience (CX) is a sprawling, multidimensional beast. It's cognitive! It's emotional! It's social! It's got mood swings!

But while firms spend money on influencers and create branded experiences that sparkle like sequins on a Vegas showgirl, they continue to treat content like the guy who parks the cars.

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

Image: Midjourney

The Role of Content (Or, Why Your PDF Might Matter More Than Your Logo)

Let's say you've bought a smart home device that promises to connect your toaster to the cloud. You're excited until you open the box, and the instructions look like they were translated by a toaster. That's not a fantastic product experience—it's a customer experience catastrophe.

Your sleek brand image didn't just take a hit—it got derailed by a help document that cheerfully opened with:

"To initiate, caress the power button until enlightenment occurs."

That's not user guidance, it's a riddle in a meditation app.

That's because content is the experience. It's the thing customers interact with when they need answers. It's their silent partner in crime during a midnight troubleshooting session. It's the difference between "I got this!" and "I'm returning this."

From Stimulus to Sob Story

The researchers behind the review unpacked over two decades of CX literature and came to a rather humbling realization: customers aren't passive recipients of brand fairy dust. They co-create meaning.

And what helps them do that?

Content.

Great content supports customer meaning-making. It lets people make sense of your product in their own messy, beautiful way. It helps them feel empowered and understood, not like they're being punished for wanting to use your product without a PhD in interface design.

Image: Midjourney

So What Should CX Leaders Do?

First, stop treating content like a neglected appendix—tacked on at the end, outdated, and quietly sabotaging your carefully crafted customer journey. Invest in it, elevate it, and give it a seat at the strategy table—preferably one without a sticky note that says "intern."

• Make content findable, usable, and enjoyable. Not "compliance-checked" enjoyable. Enjoyable.

• Connect your technical writers, marketers, and CX folks so they can create a consistent, empathetic experience.

• Let your documentation reflect your brand values—not just in tone, but in structure, accessibility, and clarity.

• Track how your content affects satisfaction, loyalty, and that mysterious "didn't call support" metric no one wants to discuss.

Getting Documentation Right: Your Secret Weapon

If we're serious about delivering exceptional customer experiences, we must realize that content is not background scenery. It's the dialogue, the choreography, the plot twist. It's when your customer decides whether they're in a story worth sticking with, or one they can't wait to leave behind.

So go ahead. Put your documentation center stage. Give your product information a standing ovation. And maybe, just maybe, your customers will give you one, too.

Cue the curtain. 🤠

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

Pretty impressive.

If you work in content marketing, you're probably exhausted. You're trying to create engaging content that builds trust, proves your brand knows what it's doing, gets people to stick around, and—if all goes well—eventually convinces someone to buy something.

All while battling the algorithm, the inbox, and the legal department.

But here's a little secret: Your technical documentation team—the folks who write the help articles no one claims to read? They're doing half your job already. And they're doing it well.

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

Image: ChatGPT

Let's Talk About Your Job

You want to:

• Attract people

• Keep them interested

• Make them trust you

• Get them to take action (buy, sign up, ask for a demo, tell a friend, whatever)

• Make your brand more visible

• Generate leads

• Keep customers happy

• Show up in search results without mortgaging your soul to Google

Now, let's talk about technical documentation. It does all of that, too.

Image: ChatGPT

Documentation Is Content Marketing For People Who Don't Want To Be Marketed To

Have you ever Googled a product question and landed on a help article that just got you?

It answered your question. It didn't try to upsell you. It was factual, well-organized, and surprisingly calming. That's documentation.

And guess what? That content often gets more traffic than your blog posts. Why? Because it's what people search for.

Think about it:

• "How do I connect X to Y?"

• "What's the difference between plan A and plan B?"

• "Can I cancel without crying?"

These are real questions asked by real humans with real intent. Your docs team is already writing answers. You, meanwhile, are trying to figure out how to turn a white paper into a TikTok.

Docs Build Trust The Slow, Boring Way (The Way That Works)

Documentation doesn't hype. It helps. And helping is what builds trust.

Marketing often tries to prove expertise by discussing innovation, leadership, and synergy. Docs prove expertise by telling you exactly which button to push and what happens if you push the wrong one. That's trust, baby.

Want to be seen as a thought leader? Link to the doc. Better yet, be the doc.

Self-Service = Self-Sell

Here's the part where it gets juicy: good documentation sells—but in disguise.

When someone finds your documentation, they're already halfway down the funnel. They're not wondering if they need a solution. They're wondering if your solution will work for them. And your help content is the difference between "add to cart" and "back to search."

SEO Without The Sadness

Docs rank. They do. Long-tail queries. Voice search. "I'm about to rage-quit" moments. Documentation is there, whispering calm instructions while your beautifully branded landing page flails in a sea of bounce rates.

Your tech docs team uses structured content. Metadata. Schema. All the things search engine optimization (SEO) pros love, are already baked in. You don't have to teach them—just copy their homework (with permission, please).

Retention, Loyalty, And The Magical Land Of "I Figured It Out Myself"

Want to improve customer retention? Make people feel smart. When they solve their own problems using your documentation, they feel powerful, capable, and like they've leveled up.

That feeling is sticky. It's also the foundation of customer loyalty.

You could send them a nurture email or give them a search bar that actually works. It's your choice.

So… Now What?

Talk to your documentation team. Bring coffee. Ask to see what content gets the most traffic. Ask the team what customers complain about. Ask them if they'll help you turn that dry but brilliant troubleshooting guide into something you can use upstream.

They've already built the library. You just need to put it in the front window.

Taking Advantage of Content Marketing’s Sensible Cousin

Content marketing doesn't have to do everything alone. Technical documentation is content marketing's shy, sensible cousin—who writes the manual, remembers a laundry list of style guide rules, and never brags about being right (even when they usually are).

It's time you collaborated.

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

You know that feeling when you’ve just nailed a project, and someone walks in with a shiny new technology and says, “Hey, we’re doing this now!” Yeah, me too. It’s like cooking an elaborate meal only to find out your dinner guests have gone vegan. Suddenly, all your hard work feels less like a triumph and more like an impressive mistake.

Welcome to the Model Context Protocol (MCP) – the new “vegan dinner guest” of technical writing. Except this time, it’s worth your attention.

The MCP Reality Check

First, a little context (pun intended). The Model Context Protocol, or MCP, is not just some shiny new jargon. It’s an open standard developed by Anthropic. Essentially, it works to help AI models access and use data from different sources, like your carefully crafted technical documentation, in a way that doesn’t make them look like confused toddlers trying to operate a can opener.

Think of MCP as the universal translator between two Star Wars droids who don’t speak the same language. It helps AI tools (and droids) make sense of data from various sources (like R2-D2’s beeps and whistles) without sounding like a garbled mess.

Image: ChatGPT

Why Bother Learning About MCP?

Look, I get it. We’re all tired of being told we must learn yet another technology to stay relevant. It’s exhausting. You’ve just figured out how to make Markdown not look like the aftermath of a typewriter fight, and now this?

Here’s the thing: MCP is helpful.

It makes your content accessible to AI agents, which means your documentation can become part of a broader, interconnected ecosystem. Imagine your technical content being capable of smoothly integrating with AI-powered support systems, or your troubleshooting guide delivering value in real time by a virtual assistant that understands what it’s saying. That’s what MCP can do.

So, What Do You Need to Do?

Start by understanding how MCP works.

MCP works like a client-server model, where MCP clients (basically AI tools with big ambitions) chat with MCP servers (the cozy little spots where your data hangs out) using a common language. You’ve got to structure your content so both humans and machines can make sense of it – kind of like explaining calculus to both a fifth grader and a quantum physicist without losing either one in the process.

If you’re already using DITA XML, you’re not starting from scratch. You just need to think about how to make your structured content accessible to AI applications through MCP. It’s like taking your well-organized closet and labeling it so your slightly robotic roommate knows where to find the winter boots without mistaking them for garden tools.

Second, make friends with your developers. I know, they’re the ones who start conversations with, “So, I tried this cool new API…” and end with, “Oops, that was production data.” But you’ll need their help to make sure your content is MCP-friendly.

They’ll love that you care about interoperability, and you’ll love that they can handle the parts with code.

Finally, don’t let the fear of sounding like a tech bro stop you from getting involved. Sure, the name “Model Context Protocol” makes it sound like a secret society where people talk about their new AI overlords. But it’s just about making your content play nicely with modern technology.

DITA XML Writers: You’re Already Way Ahead

If you’re a technical writer producing content in DITA XML using a Component Content Management System (CCMS), give yourself a pat on the back. You’ve already done most of the heavy lifting to make your content interoperable. DITA XML’s structured format makes your documentation organized, modular, and easy for machines to process. You’ve essentially created a library of well-labeled boxes rather than one gigantic, unmarked suitcase of content.

The Model Context Protocol doesn’t change how you structure your content; it just adds a way for AI tools to find and use it efficiently. Think of it this way: You’ve built an IKEA bookshelf (complete with painfully clear DITA instructions), and MCP is the moving crew that knows how to take it apart and put it back together without accidentally turning it into a wobbly pile of wood.

Your Future as an MCP-Savvy Tech Writer

Learning MCP won’t just make you more valuable to your current gig; it will future-proof your skills. Imagine being the person in the room who knows how to make content interoperable between AI agents and websites.

You’ll be the tech writing equivalent of the person who can fix the office coffee machine – indispensable and (kind of) magical.

So, take a breath. MCP isn’t here to make your job harder. It’s here to make your content more useful. And that, my friend, is worth investing a little time in – if only to keep your documentation from looking like a toddler’s first art project when AI gets hold of it.

And if nothing else, when your boss asks, “Do you know about MCP?” you can confidently say, “Absolutely. It’s like the universal translator for AI and content. Piece of cake.”

You’ll look smart. You’ll sound like you know what you’re talking about. And who knows? You might make your documentation the gold standard of MCP readiness.

Think of the bragging rights when you tell your coworkers, “Yeah, I made my content AI-ready. No big deal.”

Now, go out there and make your content a little smarter. Your future self – and probably a few overworked AI agents – will thank you.

Imagine you're deep in the trenches of a new product release, translating cryptic developer notes into something a human can read. You're not just writing—you're decoding, interpreting, and transforming a tangle of jargon into explicit, understandable content, as if rescuing it from a keyboard having a nervous breakdown.

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

Image: ChatGPT

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.

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

A special kind of rage is reserved for that moment when you need to speak to a human being, preferably one not controlled by an algorithm. The website has buried the phone number like the last bag of Halloween candy hidden from your spouse.

You scroll, click, scroll some more, and finally type something unhinged like, "WHY CAN'T I F*CKIN' SPEAK TO A HUMAN?" into the search bar. If you're lucky, this meltdown might summon a chatbot that understands English well enough to direct you to a telephone support number—the unholy grail of customer experience.

The Digital Gatekeepers

Let's address the obvious: Companies don't hide their contact information to foster a sense of adventure. They do it because they believe that if they make it hard enough, you'll either give up or figure it out alone, leaving them to sip their metaphorical piña coladas. At the same time, you wrestle with questions that are allegedly asked frequently and written by someone who has little understanding of your needs.

When the Human Touch Matters

The problem with this hide-and-seek game is that sometimes you must speak to someone. You know, someone who can hear the panic in your voice when you're trying to get a refund for the mystery charge that appeared on your bank statement. Sure, there's live chat, but let's be honest: if the conversation starts with "Hi! I'm Bot-73! How can I help you today?" you're already at a disadvantage.

Image by ChatGPT

Hiding Isn't Helping

Here's the kicker: Hiding contact options doesn't decrease support requests. It just annoys customers. It's like putting a maze between your front door and living room and expecting your guests to be thrilled with the obstacle course. People still call — except they are now angrier than they were initially.

You thought they were frustrated? Wait until they spend 40 minutes on hold only to hear they're in the wrong queue.

The Myth of the "Efficient" Support Model

There's a corporate logic to this madness, of course. Some companies think that forcing you to navigate a labyrinth of self-service options promotes "efficiency." What they're promoting is a spike in your blood pressure. Meanwhile, they boast about "streamlining" support, ignoring the screaming hordes begging for a human voice on the other end of the line.

Image by ChatGPT

Why Accessibility Matters

Imagine this: You're trying to report a fraudulent charge or cancel a subscription, and the only way to reach the company is by sending a carrier pigeon. Not much better than navigating an unmarked website. Real accessibility means offering contact options that respect people's varying needs and technological skills. Not everyone wants to type their life story into a chatbox or wait for an email response that arrives next Tuesday.

Customer Loyalty Is Fragile

Suppose you have tried to contact your cell phone provider and ended up in a queue that feels like a lifetime sentence. In that case, you know that hiding support options isn't just inconvenient—it's a betrayal. Customers remember. And when a competitor makes it easy to call them, they might take their business (and their simmering resentment) elsewhere.

The Gist: Make It Easy

Building lasting customer relationships is impossible when your organization treats customer support like a game of Whac-A-Mole.

Make it easy to call, chat, or email. Don't make us channel our inner detective just to find help. Nothing says "we value your business" quite like giving people the dignity of human connection—without the digital scavenger hunt.

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

If you've ever worked in a content management system and thought, "Surely, there must be a better way," you're not alone. Michael Iantosca—technical documentation's equivalent of a weathered lighthouse keeper yelling at ships to avoid the rocks—thinks so, too.

In his blog post, "A Graph-Based Universal Component Content Management System," Iantosca proposes a better way to manage content: combine the strengths of component content systems with the intelligence of knowledge graphs.

It’s a practical fix for a very real problem. Here's the gist, minus the jargon and caffeine-fueled despair.

Related webinar: Graph-Driven RAG AI Powered by DITA

Image generated by ChatGPT

Old Software Systems, New Headaches

Most content management systems are fine if you treat content like Lego blocks—snap one to another and pretend that context doesn’t matter. Software developers built these systems to manage chunks of content (called components) but didn't design them to understand how those chunks relate to each other. They store content well—but they fail to understand how those chunks relate to each other.

Think of them like a warehouse that stores all your boxes but forgets where each one came from or how they fit together.

Worse still, the content gets flattened—like a soufflé in a marching band—losing the nuance, context, and relationships that make it useful. That lack of context and connection becomes problematic if you care about accuracy, personalization, and keeping your job.

That lack of context and connection becomes a problem if you care about accuracy, personalization, or delivering the right information to the right audience. These systems can store your content just fine. But they can’t reason with it, and they certainly can’t help AI do that either.

Image generated by ChatGPT

Knowledge Graphs (And Why You Should Care)

Iantosca introduces the idea of using knowledge graphs—a structure that captures not just content, but the rich web of relationships between content, metadata, audience needs, product versions, and more.

A knowledge graph doesn’t just store data. It understands the data. It maps relationships. It provides context. And that context makes it possible to deliver more accurate, personalized, and AI-ready content experiences.

Instead of asking writers to manually stitch together relevance, a graph-based system knows that if a topic is part of a larger process, and that process only applies to users in Canada on version 3.2, the system should deliver only that. No hacks. No guesswork.

Image generated by ChatGPT

What A “Universal” System Might Look Like

Iantosca’s ideal system treats your content the same whether you write it in DITA, HTML, Markdown, or scrawl it on a bar napkin (okay, maybe not the napkin 😆).

It doesn’t care about format—it cares about meaning. It uses ontologies (semantic rules and structures) to help define relationships and guide how the content connects across your entire ecosystem.

It enables:

• Format-agnostic content management

• Semantic search and smart reuse

• Personalized delivery at scale

• AI integration without hallucination

Instead of flattening content into disconnected blobs, this system turns your content into a dynamic, living network. It understands the why behind the what.

From Vision To Reality

This vision of a graph-based, format-agnostic content system isn’t just pie in the sky. At Avalara, Iantosca's team is already putting it into practice. They’re using DITA to structure content, an enterprise CCMS to manage it, and a knowledge graph to map relationships across it all.

The result? Content that’s easier to find, tailor, maintain, and serve—whether it’s for human readers or AI systems trying to answer customer questions without guessing.

Image generated by ChatGPT

Why It Matters —> Now

Technical content is no longer just documentation—it’s infrastructure. And if we expect that infrastructure to support everything from customer self-service to intelligent chatbots, we can’t afford systems that treat content like static blobs.

Iantosca’s argument is clear: we need a new foundation. One that understands how content works, how it connects, and how it serves real users in real contexts.

And we need to build it now—before the old systems start causing new problems we can’t patch with duct tape.

Read Iantosca’s paper. 🤠

I’ve been volunteering at our local elementary school in the school library. This week, the creative head librarian held a “book tasting party” where she placed books of different genres at six different tables and had class groups rotate from table to table to “taste” each type of book. From horror to graphic novels, there was a book genre for many tastes.

Photo by Pritesh Sudra on Unsplash

Imagine if you could have a “flight” of docs sites to have a docs site tasting party! The docs aficionado in me wants to go to such a party. What would be served? How about a taste of Sphinx, Astro, Hugo, and Jekyll, with a final taste of Mkdocs and Docusaurus? Let’s have fun with it (even if the metaphor breaks down quickly).

Sphinx: The Rich Espresso for Documentation

Sphinx is a powerful documentation generator initially created for Python projects. It excels at producing structured, text-heavy documentation emphasizing cross-referencing and indexing. Using reStructuredText as its markup language, Sphinx offers robust extensibility through various plugins and themes. Many technical documentation teams appreciate its ability to generate outputs in multiple formats, including HTML and PDF. However, its complexity can be daunting for newcomers unfamiliar with its syntax or configuration.

Astro: The Sparkling Citrus Spritz of Static Sites

Astro is a modern static site generator designed for speed and flexibility. Unlike traditional SSGs, Astro allows developers to mix and match different frontend frameworks like React, Vue, and Svelte while focusing on shipping minimal JavaScript to the browser. This approach makes Astro an excellent choice for performance-conscious documentation sites. With its component-driven architecture, Astro enables content creators to build engaging doc experiences while maintaining simplicity in content management.

Hugo: The Smooth Bourbon of Speedy Site Generation

Hugo is one of the fastest static site generators available, and it is known for its speed and efficiency. Written in Go, Hugo boasts nearly instant build times, making it a favorite among developers who need quick iterations. It uses Markdown for content and has a powerful and flexible templating system. Hugo is ideal for large-scale documentation sites, thanks to its excellent support for taxonomies, multilingual content, and customizable themes. However, the learning curve can be steep for those unfamiliar with its templating language.

Jekyll: The Classic Red Wine of Static Sites

Jekyll is a well-established static site generator that powers GitHub Pages, making it a popular choice for open-source projects. Built with Ruby, Jekyll processes Markdown files and converts them into static HTML. Its simplicity and deep integration with GitHub make it an appealing option for developers looking for an easy way to deploy documentation. While Jekyll offers plugins and themes, its speed and flexibility may not match newer SSGs like Hugo or Astro. Still, it remains a reliable choice for lightweight and version-controlled docs sites.

MkDocs: The Refreshing Iced Tea of Documentation

MkDocs is a straightforward static site generator designed explicitly for documentation projects. It prioritizes ease of use with a simple configuration file and Markdown-based content. MkDocs includes a built-in live preview server, making it easy to see changes as you write. One of its most popular themes, Material for MkDocs, enhances the experience with modern styling and extra features. While MkDocs may not be as extensible as Sphinx, it is an excellent choice for teams looking for a quick, efficient way to publish documentation.

Docusaurus: The Trendy Matcha Latte of Docs

Docusaurus, developed by Facebook, is a React-based static site generator optimized for documentation sites. It provides out-of-the-box support for versioning, internationalization, and a structured navigation system. Docusaurus embraces a modern development approach, allowing developers to leverage React components for interactive documentation. Its ecosystem includes a vibrant community and a growing number of plugins. While its reliance on JavaScript may be a drawback for those seeking pure static solutions, Docusaurus remains a top contender for teams wanting a dynamic, developer-friendly documentation site.

The post A Flight of Static Site Generators: Sampling the Best for Documentation first appeared on Just Write Click.

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

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

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

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

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

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

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

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

 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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