Alden DeSoto

/aldendesoto

Alden DeSoto

Bringing products and ideas to life with compelling content

User Avatar

Alden DeSoto

2y ago

Stop Writing, Start Designing: What Technical Writers Can Learn from Content Designers

No one wants to read technical documentation. Yet, we sometimes write as though we're in a delightful conversation with readers.

Sorry, technical documentation is not a conversation and it's not delightful.

This is where we can learn from content designers.

Content designers don’t just write—they design an experience. Here’s how their approach differs:

1️⃣ Know the Outcome:
Content designers are intentional about understanding the user’s goal. They research, build personas, and map out user journeys to pinpoint what the user needs—and nothing more.

2️⃣ Content designers optimize for reduced cognitive friction. Users aren't even aware they're reading.

3️⃣ Prioritize Design Over Words:
Content designers think beyond text. They collaborate with product, design, and research teams to ensure that the experience—not just the writing—is intuitive and effective.

In contrast, technical writers sometimes over-focus on “delivering the doc” when instead we should ask "Why does this doc exist in the first place? How can we simplify it or eliminate it completely?"

Technical writing often happens in a relative silo. We consult with SMEs for information, but how often do we engage with UX researchers and product designers to shape the learning journey?

Get out of the user’s way. The fewer words, the better.

Less author, more designer.

#TechnicalWriting #ContentDesign #UX #UserExperience #WritingTips

User Avatar

Alden DeSoto

2y ago

Metrics like Pageviews, Time on Page, etc aren't useful for measuring content effectiveness. Try this instead to get better signal.

Pageviews, Time on Page, Bounce Rate, Satisfaction Rate (% of users who answered Yes to "Was this article useful?") and similar metrics aren't helpful.

They measure engagement with the documentation, not the product.

Let's say you have a high Time on Page for an article. Is that good? Maybe. Maybe not. And what if Time on Page is low? Do you know what to fix? Probably not.

If an article has a low Satisfaction Rate, does that tell you what to fix? It does not.

Try this instead:

1. Collect all the comments left by the users who were not satisfied. Load all the comments into a spreadsheet.

2. Categorize the comments into themes. (Anywhere from 3 - 10 themes, depending upon how many comments you have. Don't get too granular.)

Example: If a lot of comments complain that the information is too complicated, create a "too complicated" theme. Group all those comments together.

Example: If a lot of comments complain that they couldn't complete Procedure XYZ, create a "Couldn't complete Procedure XYZ" theme.

Tip: Use AI to scan your comments and identify the top themes.

3. Count the number of comments in each theme. Calculate the percentage of comments that fall into each theme. Often, you'll have a very large percentage of comments in one or two themes.

You now have data that communicates the nuances of user challenges. For example, "X% of negative comments complain that they can't complete XYZ and Y% of negative comments don't understand the terminology."

The product team will love you for sharing this data. More importantly, it gives you actionable information.

4. Now update your docs to address your top problem themes.

5. In two weeks, come back and repeat steps 1, 2, and 3. If you've done a good job addressing the problem areas, you'll find that your top themes HAVE CHANGED. In other words, users are still complaining, but now they're complaining about something else!

For example, "In September, X% of comments complained that they couldn't complete procedure XYZ, but in October, negative comments shifted to A, B, and C ... etc"

You can now see and communicate progress to your Product and UX teams, which they will appreciate.

Don't be satisfied with vanity metrics. Dig deeper and find the data that helps you iterate.

User Avatar

Alden DeSoto

2y ago

Tech writers and content designers: Want to demonstrate impact? The HEART framework can help.

Many writers and UXers struggle with communicating the impact of their work. Showing impact takes time, but if you articulate a strategy and a North Star, your leadership will actively support you.

First, shoot for AT LEAST ONE of the following outcomes:

1. Increase adoption, engagement, and retention

2. Reduce support costs

3. Build user trust

This maps pretty well to the HEART framework, developed at Google, which breaks down product success into 5 areas:

Happiness

Engagement

Adoption

Retention

Task Success

Let's look at each one.

Happiness:

User trust is key. Do you proactively explain product changes to users? Do you listen to customers and teach them how to be successful, or does your content simply document product features? Monitor Product CSat and Net Promoter Score. Don’t rely on knowledge base CSat; it measures how happy users are with the content, not your product.

Engagement:

Create online courses and certifications to build a passionate base of power users. More tactically, lead with examples in knowledge base articles. Measure effectiveness with Average Session Length, Conversion Rate, and similar metrics.

Adoption:

Speak to users in their language, not your product jargon. If your content assumes that new users know your product terminology, you’ll have a hard time driving adoption. Use a metric that measures initial opt-ins, e.g. N of Accounts Created.

Retention:

As users become more sophisticated, does your content grow with them, addressing use cases they hadn’t considered? A common metric is Churn Rate, but use whatever metric captures the nuances of your product.

Task Success:

When users can’t complete tasks, they request support. This is expensive. A high Escalation Rate suggests that your knowledge base is not doing its job. Also look at Avg Time to Resolution because customers often request support even when the knowledge base has the information they need. In these cases, the support rep can simply reply with an article link and quickly close out the ticket. A high Escalation Rate with a low Average Time to Resolution suggests that the content might be fine, but needs to be more discoverable.

Of course, credit for these metrics has to be shared with the rest of the product team. But HEART gives you a strategy and North Star that will make sense to leadership and your cross functional teams.

User Avatar

Alden DeSoto

2y ago

Tech writers: Do you struggle with getting SMEs to review your docs? Try this approach.

You're so proud of your completed draft and now you just need folks to review it. But your reviewers keep putting it off. You've tried begging, guilting, reasoning, and bribing, but it's taking forever to get the doc reviewed. Sound familiar?

Newsflash: No one wants to read a long doc, let alone review it.

Your SME knows the docs are important, so they will get to the review "as soon as they can" -- but not today. They'll put it off as long as possible.

That's what happens with large, poorly defined tasks.

Try this instead. Don't wait for a complete draft to ask for a review. Instead, verify your understanding of the product in real time.

Let's say that you're working on your draft in a Google Doc. Comment the paragraph or statement in question and assign it to the SME:


"@SME Is this an accurate statement?"

Alternatively, send them an email / Slack / chat etc:

"Hey SME, is it accurate for me to say the following? [insert text you want to write]".

Pro Tip: Italicize your proposed text. Trust me, it helps. I don't know why.

Most SMEs would rather answer individual questions -- even a lot of questions -- than review a doc. Intelligent questions will feel like normal collaboration to them.

You will be respected as someone who does the background research and is involved with the product. And many of the questions you ask will surface quirks and unresolved issues. The product team will appreciate this.

By the time you get to a final draft, you won't need to have it reviewed.

SMEs often don't know what you need when you dump an entire draft on them. Some SMEs might think that you need them to review the writing or the doc structure. You don't. (Ask other writers to review your writing, don't ask SMEs.)

If you have a hard time believing that you should not ask SMEs for a final review, consider this: Does an investigative journalist ask the subject of an article to review the article?

Of course not. A journalist verifies all the facts, usually by asking the right questions, then writes the piece and stands behind it.

A by-product of this approach is that it forces you to deeply investigate your subject matter. It won't work if you ask lazy, open-ended questions.

Follow this approach and you'll never be blocked on doc reviews again.

User Avatar

Alden DeSoto

2y ago

Think documentation quality doesn't impact platform adoption? Here's how one AI platform loses out to another because of the documentation.

I built Docs-writer.ai using an Open AI Assistant. I'm an ex-Googler and would have preferred to use Gemini and a custom Gem. So, why didn't I?

I assumed there was no API access to Gems. It's not documented on AI.google.dev. At least, I can't find where it's documented.

Gemini couldn't do what I wanted. Even though it can.

In contrast, platform.openai.com has a clearly marked section titled "Assistants". So, Open AI can do it and Gemini can't. Easy choice. I'll use Open AI.

Open AI does a better job of promoting their platform, with better designed developer resources.

Here's the takeaway. Identify the top use cases that will drive adoption for your platform and design your documentation around them.

Because if a user can't find the documentation, your feature doesn't exist.

User Avatar

Alden DeSoto

2y ago

Product teams: Want to create a seamless UX across your product suite? Here's the foundational activity that often gets dropped.

It's creating a glossary of product terminology.

On small teams, a glossary is less critical. Yet it usually gets created. The UX Lead, Tech Writer, Product Lead -- or someone -- calls it out.

For large teams working on a suite of products, a glossary is critical, but often neglected. It's the classic "I assumed someone was working on this".

Inconsistent terminology across products negatively impacts adoption and growth. It increases support costs. And it makes it harder for a large team to align internally. So much for effective cross-functional collaboration.

At the very least, you're shipping your org chart. And your customers have the opposite of a "seamless experience".

Trying to wrangle terminology for a product suite after the fact is difficult. It's technical debt. Like all technical debt, it's expensive to pay off. Way more expensive than doing it right in the first place.

Here's my call to action:

Product Managers: If you have content designers and technical writers on your product team, ask them to work together on a glossary. Ask about it _now_, before you get too much further down the line.

Content designers, technical writers: Don't wait to be asked. A glossary should be one of your first work streams when starting on a new product or product area.

It's so much easier when everyone speaks the same language.

User Avatar

Alden DeSoto

2y ago

Concerned about AI taking over your technical writing job? Master these 2 skills and AI won't be able to compete with you.

1. Be an expert on the product you're documenting.

Try it, test it, break it.

You'll offer much more value to the product team if you're a user yourself. If you've experienced first-hand the frustrations of on-boarding and using the product, you can offer invaluable feedback to the product team. You can help design a product that needs less documentation. And, your battle scars with the product will make you a more empathetic and effective writer.

Install your own instance of the product. Create a sandbox where you can experiment. Come up with a use case, however contrived, and implement it as an example.

First-hand experience is the only way to learn. Do not trust that everything works the way the product team thinks it works. IT DOESN'T ! I guarantee that you will uncover behaviors and workarounds that no one else knew existed.

2. Review user feedback and iterate.

No one gets it completely right the first, or even the fourth time. Never publish content without regularly reviewing the user feedback. Review user comments at least weekly for a new feature. Then go back and adjust the docs based on what you learn.

Also, share these user insights with the rest of the team. The UXR team will love you for this.

Never ever write content, throw it over the wall and call it "done". That's what AI does. And that's why it's called "artificial" intelligence. In contrast, you get to show up with human intelligence.

In summary,

1. Be an expert

2. Iterate

User Avatar

Alden DeSoto

2y ago

Overheard from a senior leader: "Why don't you just use AI to generate the UI text?" Maddening, right? Take a deep breath and let's unpack what's going on here.

There's more to what we do than filling up a screen or a page with words. That's why it's so maddening to hear "Why don't you just use AI?"

We do important Work. The Work is a rich combination of collaboration, design, research, audience awareness, experimentation, hacking, iteration, and yes, writing craft.

Here's the problem though. From our senior leader's perspective,

Writing = The Work

This isn't accurate. The writing is an artifact of The Work, not The Work itself.

Yes, we're writers. But we're also designers of experiences. We empower users to be successful.

Here's my call to action: Frame your work less in terms of tactics (what you wrote) and more in terms of strategy.

Focus on the outcomes of your work, the engagement, the serviceability wins, the adoption gains, the user insights, the usability results.

Maybe then we'll hear less "Why not just use Chat GPT?"

User Avatar

Alden DeSoto

2y ago

"When Your Documentation IS the Product", or "Why I used Open AI Instead of Gemini for my AI Application":

I built Docs-writer.ai using an Open AI Assistant (Custom GPT) as my back-end. I could have built Docs-writer using Gemini and a custom Gem. I didn't because programmatic access to a Gem is not documented on AI.google.dev. At least, I can't find where it's documented.

And if a user (like me) can't find the documentation, the Feature. Doesn't. Exist.

Gemini couldn't do what I wanted. Even though it can.

In contrast, platform.openai.com has a clearly marked section titled "Assistants". So, Open AI can do it and Gemini can't. Easy choice. I'll use Open AI.

This isn't to cast shade on Google's docs, which are written by very capable, smart people. Or on Gemini, which is an awesome product.

Here's my message to product teams: The docs shouldn't be an afterthought. Get clear on your use cases. Design your documentation around those use cases. Because if it's not documented, it doesn't exist.

P.S. If you've read this far, LMK in the comments which is the better title for this post: "When Your Documentation IS the product" or

"Why I used Open AI Instead of Gemini for my AI Application"

User Avatar

Alden DeSoto

2y ago

Product teams: Want great user documentation for your product? Here's the single most important step that most people miss. (Yes, even many tech writers miss this.)

Here's the missing step: Decide what "good" looks like. What's your objective for publishing this article / help center / explainer video / developer documentation / etc ? What results would you ideally like to see?

Once you're clear on your desired outcome, you'll have a good idea of exactly what needs to be in the article. And once you know that, your article might practically write itself. (More on this in a minute...)

For a new product, "good" usually = adoption. The user documentation must answer the questions new users will have. It must remove, or significantly reduce the friction to adoption.

For a mature product with strong adoption, "good" = serviceability. The user documentation must reduce the number of support requests.

Now that you're clear on what your article needs to accomplish, how might it "practically write itself"?

Your PRD already has most of the information/use cases/examples/etc that users need to successfully adopt your product. It just needs to be presented in a user friendly format that includes only the information relevant to users.

Paste your PRD into ChatGPT / Gemini / etc and ask it to draft your article. ChatGPT does a pretty good job of this. Even better, paste your PRD into Docs-writer.ai, which I created specifically for this purpose. Docs-writer.ai is free, you'll get better results, and you won't spend time refining prompts to get what you want.

To wrap up: Get clear on your objective. Don't skip this step. Your users will thank you and you'll improve product outcomes.