Showing posts with label technical writing. Show all posts
Showing posts with label technical writing. Show all posts

What I’ve learned writing for billions of users

Mike's Notes

I came across this gem in Smashing Magazine.

"What are the takeaways from writing for billions of users across dozens of languages, time zones, and cultures? Nick DiLallo has summarized everything he has learned writing for products used by a meaningful percentage of the world’s population. The result is a list of 70 valuable lessons learned that you can apply to your own writing right away." - Smashing Magazine

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library > Subscriptions > Smashing Magazine
  • Home > Handbook > 

Last Updated

25/08/2026

What I’ve learned writing for billions of users

By: Nick DiLallo
Medium: 03/08/2026

Nick DiLallo is a writer based in Brooklyn. Past clients include Apple, Airbnb, Etsy, and Google. He currently leads UX writing at Clay.

...

Insights from products that grow and grow.

...

A few years ago, after running a complex global product launch, I wrote down everything I learned. To track my own ideas. To make sense of things. I’ve kept adding to it ever since.

I’ve worked on products used by a handful of people and products used by a meaningful percentage of the planet. The second kind taught me things the first never could.

This is what I’ve picked up along the way, writing for billions of users across dozens of languages, time zones, and cultures. Some of these lessons are about words. All of them are about people.

...

01: Most interfaces are mostly words. Take away all the text and screens stop making sense.

02: When you have a giant user base, people will interact with your product in ways you never intended. You’ll be shocked. You’ll also learn from them.

03: Good interfaces don’t need instructions. If you need to write things like “look for the arrow” or “scroll right,” the UI needs fixing. Words shouldn’t explain the design.

04: Naming features is hard. Renaming them is nearly impossible, especially if millions of people have already started using the product. You get one chance to get it right.

05: The typeface matters as much as the writing.

06: People have high expectations for software, and that includes the writing. World-class products don’t have mistakes, typos, or clunky phrasing.

07: Saying one thing is better than saying two or three things.

08: Fixing the writing can fix the entire company. Support tickets go down by the thousands. Conversion goes up. Users stay longer. There’s a reason the world’s best companies hire and value talented writers.

09: A shorter sentence is almost always a better sentence.

10: It’s always a good idea to fix things. You don’t need a rigorous business case for it. Don’t waste time trying to calculate the ROI of spelling “Connecticut” correctly.

11: People won’t read everything you put in the interface. They’ll skim and scan and scroll to what they want. You need to write for those people.

12: Rewrite everything twice. Rewrite important things twelve times.

13: Our relationship with technology changes. Writing can shape that change. Remember, we used to be afraid of using our real names online or entering our credit card.

14: Good writing just feels different. This can be hard to explain to non-writers. There’s a certain kind of click that happens in your head. Revise until you get there. You’ll know it when it happens. Developing this instinct takes a long time.

15: With a giant user base, you can get stuck trying to write “for everyone.” Try writing for one specific user. An Olympic athlete struggling to set a new record. A first-time mom who’s using your product at 4am. A surfer on their honeymoon in Tahiti. Choose one person and write.

16: Longer writing needs to be worth it. We expect more from a paragraph than a headline. Make everything the right length.

17: Users will read what you wrote, then do the exact opposite. It’s okay.

18: Details matter. The best teams spend time arguing over formatting and punctuation. Is it $45 or $45.00 or 45 (USD)? Do we say “July 5th” or “Next Tuesday”? Is it Settings or Preferences? You need to decide.

19: More opinions can sharpen your work.

20: Sometimes the last thing you need is more opinions.

21: A perfect error message is still an error message. Try to fix the root cause. Smarter inputs, clearer phrasing. An error is a last resort.

22: Words can’t do everything in an interface. Understand where other forms of information can help. A great description of a hotel room is no match for a photograph. A street address doesn’t show the same context as a full map.

23: Writing quality signals product quality. Users make judgments based on the writing. You can’t ask someone to trust you with their private data if they can’t trust you with your commas.

24: Small wins add up. A clearer headline here. A shorter error message there. A more direct call to action somewhere else. Fix enough little things and the product will completely transform.

25: Actions matter more than words. You can’t write one thing and do another. Don’t call it a “free trial” and then require a credit card. Don’t say chats are private if they aren’t. If you’re using writing to hide features or “convince” users, that’s a problem.

26: Most brand voice guidelines aren’t very helpful. Because most don’t say anything interesting or unique. Calling your brand voice “human” is not enough.

27: It’s usually a good idea to trust writers with writing. I’ve seen products fail because the wrong person was making decisions about words.

28: Grammar should be internalized. Learn the rules and break them when it feels right. But don’t talk about grammar too much. Using the phrase “past participle” in a meeting won’t get anyone excited. It’ll make them think of high school English class.

29: It’s hard to scale your product with a vague, meaningless value prop.

30: Tell the truth. I’ve seen a single vague sentence generate more support tickets than an actual outage. If something will take nine minutes, say it will take nine minutes.

31: Don’t invent words when you don’t need to. Digital products have a shared vocabulary that users already understand. Stick with common words and phrases. Log in. Save. Delete. Update. Edit.

32: Be careful about overwriting. This was something I saw lots of products doing for a long time, adding too much personality and too much text. Making a product “conversational” can sometimes just make it annoying to use.

33: A great onboarding will solve much more than an endless help center. First-time users who get confused don’t file tickets. They just leave.

34: You can’t evaluate writing in a spreadsheet or doc. Put the words in the interface and see how they read. Read them in the prototype. Read them on the device you’ll be using. Get as close to the real experience as possible.

35: Language is always changing. It happens faster than you think, and it’s the job of a writer to keep up. Look at the way people younger than you communicate, or the way your parents email. Nobody’s right or wrong. Language just moves.

36: Write without My or Your. Don’t call it My Photos or Your Photos. Just call it Photos. If you don’t, you’ll be chasing this down forever and confusing everyone along the way.

37: Writers who understand how products are built make better decisions. Learn as much as you can about strategy, technology, and business. A writer should understand how a company makes money and what their long-term vision is. Get as close to the decision-makers as possible.

38: Come back and read it tomorrow. Time away always helps.

39: If someone is using your product, they’ve already decided. Don’t market to them. You might talk them out of it.

40: Pick a word for something and use it everywhere, across every screen, for every user. Don’t call it a “folder” on one screen and a “workspace” on another.

41: Trust your own instinct as much as you trust your user research.

42: Users don’t know — or care about — your org chart. Your brand should have a single voice. It doesn’t matter if your emails, notifications, and support documentation come from different teams. Get everyone aligned.

43: Be careful with playfulness. A button that says “Pay” is clearer than one that says “Ka-chingggg.”

44: Word and image should work together. Give users context.

45: The things we build often reflect who we are. Selfish people build selfish products. Kind people build kind ones. To build the best product, build the best team and hire the right people.

46: Remember that translating for global products is a lot more complicated than swapping out text. Different languages reflect different cultures — and sometimes entirely different ways of thinking.

47: Be careful about making too many decks. You’ll start thinking in keynotes and bullet points, not UX and interface decisions.

48: Language has power. Writing makes people laugh and sob and get angry and feel joy and connect with other humans. A gradient can’t do that. A date picker or corner radius can’t do that.

49: Sometimes words can convey multiple meanings. “New” can mean exciting, but also unproven. Calling a transaction “safe” might make the user worry. Think about every word and what else it might be saying.

50: Not everything needs a login or account. Let people use your product. If they like it, they’ll stick around.

51: Not everything needs to be a subscription, either.

52: You get better by writing more. There’s really no shortcut to this one.

53: Know that your tools as a writer will keep changing. You’ll be working differently and using new software in 5 years. Maybe sooner.

54: One of the biggest challenges you’ll face is translating your product into right-to-left languages like Arabic or Hebrew. The entire UI starts to break. Icons, progress bars, and indicators might appear backwards. Build a writing system that can flex across all layouts and languages.

55: Never, ever mess around with money. There is no faster way to lose trust or infuriate a giant user base. Tell people what things cost. Don’t add “convenience fees” at checkout. Keep auto-renew off by default.

56: Good writing can’t fix a bad product. But it can reveal problems faster.

57: Get the first draft done. A bad draft is better than a blank screen.

58: Bringing writers in early is always a good idea. You can tell when a writer was added to the team the week before launch.

59: Delete as much as you can.

60: Good writing is not enough. You also need good layout, hierarchy, and typography.

61: The legal team will ask you to add words. Rewrite them so they make sense to regular people.

62: Laws are different everywhere. Required disclosures in Australia are different from those in California or the EU. Create different versions of the same screen if you need to. Don’t try to create one “hero version” that appeases everyone. It will end up being the clunkiest option.

63: Avoid the word “content.” It devalues everything it tries to describe. A film is not “content.” Writing is not “content.”

64: Users aren’t stupid. But they’re sometimes busy or distracted or tired.

65: Your writing will teach people how to think about your product. Clear language creates clear thinking. Vague or inconsistent language does the opposite.

66: Deliver bad news quickly and clearly.

67: Write for the user, not the press release or launch video. Too many companies get this wrong. They start with the marketing assets and then try to build the product around it. It usually doesn’t go well. Designing a screen for a keynote is different than designing it for a user, and great marketing won’t ever be able to fix usability issues.

68: It’s better to write something well the first time. A ten-second fix, multiplied across a billion sessions, is measured in years, not minutes.

69: If you’re making changes but things aren’t getting better, try fixing something other than the words. Use different components. Add animation. Adjust the navigation. Keep trying new ways to make the UI better. Don’t just rewrite. Rethink.

70: Accessibility can’t be layered on top of good writing. Turn on a screen reader and listen to your own writing. Use your product with different settings. You need to understand how people actually use your product, then write for them. All of them.

71: Build writing guidelines and documentation in the tools your team actually uses. Don’t make a PDF that never gets opened.

72: Users notice inconsistency before they notice almost anything else.

73: If you’re stuck, close your laptop and go outside.

What is Diátaxis and should you be using it with your documentation?

Mike's Notes

I rediscovered this article by Technical Writer Tom Johnson while figuring out how to get the Pipi 9 CMS Engine (cms) to successfully integrate support material and learning documentation into the workspaces.

The actual Pipi 9 code base has no comments. Pipi writes the code and adds a metadata stamp, so why would it need comments? All documentation sits in parallel structures. This closes some doors and opens others.

Pipi 9 uses a structured combination of;

  • Read the Docs
  • Learning Objects
  • Diátaxis
  • The Good Docs Project

Information Pattern

Inspired by Read the Docs.

The whole is composed of Learning Objects in composable hierarchical structures. Each Learning Object

  • Is of one Diátaxis type
  • Uses one Good Docs Template

Learning material is presented in this default order because apparently it works for most people.

Tutorials > How-to guides > Technical reference > Explanation

Users can, however, explore learning material in any way that works for them and set it as a learning preference.

Show, not tell 

In my case, I like to see a diagram, then watch a talk with slides because I'm curious, then read the reference so that I can reverse-engineer to build a working model in my head, then a demo for the ahaha moment to confirm the model. Then an explanation to fill in the gaps, then a how-to guide and finally a tutorial to find the start button.😊 Worked examples are essential, because it gives me a pattern to start with and then change.

We all learn differently.

Ajabbi will need an excellent Technical Writer to improve what I have written, providing top-notch documentation and reducing complexity for readers.

Resources

References

  • Documenting APIs: A guide for technical writers and engineers. By Tom Johnson.

Repository

  • Home > Ajabbi Research > Library > Subscriptions > I'd rather be writing
  • Home > Ajabbi Research > Library > Learning > Learn API Docs
  • Home > Handbook > 

Last Updated

08/12/2025

What is Diátaxis and should you be using it with your documentation?

By: Tom Johnson
I'd rather be writing: 18/10/2023

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

Summary

The Diátaxis approach to documentation organizes technical documentation into four types — tutorials, how-tos, reference, and explanation. In this post, I compare Diátaxis to DITA, Information Mapping, and the Good Docs Project, explaining similarities and differences. I also point out why identifying information patterns can be so worthwhile as a technical writer, and how identifying these patterns not only grounds our practice in the larger practice of rhetoric but also gives us useful patterns to use with AI tools.

Introduction

One topic I keep seeing surface in various places online is Diátaxis. Here are a few places I’ve seen it surface:

  • Upcoming webinars — see Introducing the Diátaxis Approach to Technical Documentation on the Content Wrangler’s BrightTALK
  • PyCon talks — see What nobody tells you about documentation
  • Reddit threads — see Diátaxis, a pragmatic system for technical documentation writing
  • Tutorials that mention it — see API tutorials beyond OpenAPI
  • Discussions among Python doc groups — see Adopting the Diátaxis framework for Python documentation, and more.
  • You can read more about it here: Diátaxis. It seems Diátaxis is gaining some traction in the technical writing community.

I knew Diátaxis involves organizing docs into four specific content types: explanation, reference, tutorials, and tasks. But I was fuzzy on most other specifics. The constant references to Diátaxis made me wonder, what am I missing? Is there something new here? Is this how I should be approaching the structure of my own documentation? And why is Diátaxis growing in popularity? What’s unique about the approach, and how does it differ from DITA?

Diataxis diagram

What is Diátaxis?

The Diátaxis approach divides documentation into four distinct content types:

  • Tutorials - Lessons that provide a learning experience, taking users step-by-step through hands-on exercises to build skills and familiarity.
  • How-To Guides - Practical guides focused on providing the steps to solve real-world problems.
  • Reference - Technical descriptions and factual information about the system, APIs, parameters, etc.
  • Explanation - Background information and conceptual discussions that provide context and illuminate topics more broadly.

The key premise of Diátaxis is that each content type serves a different user need and has a distinct purpose. Keeping them separated allows the content to be tailored and structured appropriately for that specific goal.

What does “Diátaxis” mean?

The name Diátaxis derives from Ancient Greek roots meaning “arrangement” or “layout.” It combines the Greek prefix dia, meaning “across”, with taxis, meaning “arrangement.”

This linguistic root relates to the organizational nature of the Diátaxis documentation approach. At its core, Diátaxis provides guidance for thoughtfully structuring documentation content into different categories based on user needs. The Diátaxis approach takes a jumble of disparate content and systematically arranges it into a meaningful, structured information architecture optimized around user goals.

Why follow the Diátaxis approach?

Here are some key benefits and promises of the Diátaxis approach:

  • Helps users find what they need more easily since content is organized by their goals.
  • Allows writers to focus on the type of content instead of wrestling with how to fit it into a less structured documentation system.
  • Serves both beginners and experts more effectively by separating learning content from reference.
  • Prevents muddling of content types, such as conceptual explanations in a how-to guide or instructions within a reference doc.
  • Provides a consistent, structured model for organizing documentation across products.
  • Promotes better quality content overall by keeping each type focused on its primary user need.

Who is Daniele Procida?

Daniele Procida developed the Diátaxis approach to documentation. Although he has a background in philosophy, Procida has been in the tech industry for a decade now, and has been involved in open-source software for even longer. He is currently an Engineering Director at Canonical.

Comparing Diátaxis with other approaches

As an approach for documentation, Diátaxis shares some similarities with other models.

How does Diátaxis compare with DITA?

DITA users will see quick comparisons with task, concept, and reference, but beyond these overlaps, DITA and Diátaxis actually have a lot of differences:

  • DITA is a formal XML-based standard maintained by the OASIS standards organization. It consists of XML schemas that content must validate against. Diátaxis isn’t an XML schema and doesn’t require validation.
  • DITA has a strong ecosystem of CMS tools and publishing systems built around its XML architecture. Diátaxis is not tied to specific tooling.
  • DITA defines a few more core topic types than Diátaxis, including troubleshooting, glossary, and generic topics. Diátaxis focuses on just four main types: tutorial, how-to, reference, and explanation.
  • DITA allows creating custom topic types through a specialization mechanism. Diátaxis doesn’t have extensibility for new types, as it’s not an XML schema.

Diátaxis has a more prescriptive recommended information architecture based on inherent user needs. DITA is more agnostic about optimal structures. For example, you can assemble the tasks, concepts, and reference types into whatever arrangements you want.

DITA emphasizes content reusability through topic-based authoring. The core idea is that componetizing information into these building blocks allows for efficient reuse across different deliverables (PDF, web, and more). Diátaxis isn’t concerned about content reusability and re-use across multiple outputs.

How does Diátaxis compare with Information Mapping?

DITA also shares some origins with Information Mapping, a technique developed by Robert Horn in the late 1960s. Although many details about Information Mapping are restricted by a paywall, here’s a brief comparison of Diátaxis and information mapping based on the information from Iva Cheung’s Introduction to Information Mapping post.

Cheung says Information Mapping identifies the following information types:

  • procedure—e.g., instructions on how to do something
  • process—e.g., description of how something works
  • principle—e.g., description of a standard or a convention
  • concept—e.g., description of a new idea or object
  • structure—e.g., description of an object’s components
  • fact—e.g., empirical information

You can see similarities here with other approaches. Diátaxis’ explanation is similar to principles and concepts. Reference might related to structure. How-to guides might relate to procedures and processes. I’m not sure what “fact” is, but perhaps it shares intent with tutorials.

Cheung says information management uses these three principles:

  • Chunking: group information into small, manageable chunks.
  • Relevance: limit each group or “unit of information” to a single topic, purpose, or idea.
  • Labelling: give each unit of information a meaningful name.

Here Information Mapping seems more similar to DITA than Diátaxis, in that information is broken down into small chunks with single ideas. The labels, however, seem unique to Information Mapping and interestingly seem to share commonality with embedding techniques used when preparing information for LLMs.

How does Diátaxis compare to The Good Docs project?

Both the Diátaxis approach and The Good Docs Project are focused on identifying best practice patterns and templates for technical documentation, but they approach it differently.

Diátaxis defines 4 core content types — tutorial, how-to, reference, and explanation. In contrast, The Good Docs Project has developed a set of templates mapped to various technical doc types and needs, including:

  • API quickstart
  • API reference
  • Code of conduct
  • Explanation
  • How-to
  • Installation guide
  • Logging
  • Our Team template
  • Overview
  • Quickstart
  • Style guide
  • Release notes
  • Troubleshooting
  • Tutorial

While Diátaxis focuses on the high-level IA, Good Docs provides more tactical templates and writing guides tailored to each type.

Good Docs templates help authors avoid “blank page anxiety” and provide examples with embedded best practices. In contrast, Diátaxis provides more general principles to help guide what should go in each content type.

Why is Diátaxis so popular?

I believe Diataxis is gaining popularity in part because it reveals discernible information patterns within documentation. The approach defines distinct information types, which helps writers recognize structures for organizing content tailored to specific user goals. By defining various information patterns, the Diátaxis helps writers shape and organize content.

The concept of information patterns extends far beyond documentation. For example:

  • Blog posts often follow story patterns.
  • Academic papers have a standard IMRaD pattern (intro, methods, results, discussion).
  • White papers use problem-solution patterns.
  • Knowledge base articles need clear question-focused patterns.
  • Speeches rely on patterns like the three-part list.
  • Legal documents leverage definitions, clauses, sections.
  • Marketing emails use subject lines, preview text, calls-to-action.

Seeing these patterns is like glimpsing the matrix behind communication. Understanding and applying patterns is at the core of rhetoric and document design.

The ability to identify and leverage information patterns in communication is central to the study of rhetoric. Rhetoric is often misunderstood as meaning language intended to manipulate or persuade. But its original definition is using language and information structuring techniques to fit a particular purpose, audience, or situation.

This is why so many technical communication academic programs are housed in rhetoric departments. The rhetorical tradition is fundamentally concerned with patterns of communication — how to shape content to achieve goals like persuading, informing, or motivating an audience.

Technical communicators are modern practitioners of rhetoric. Our job is fitting content to the expected discourse for optimal communication, comprehension, and usability.

Breaking down the Diátaxis information patterns

Let’s briefly look at the information patterns that Procida makes explicit. We’ll look at each information type and describe the salient characteristics.

Diátaxis information patterns

Information patterns in tutorials

In the Diátaxis approach to documentation, a tutorial is “a lesson, safely in the hands of an instructor” that provides a guided, hands-on learning experience.

Whereas DITA focuses on tasks/procedures, tutorials have a different rhetorical shape tailored for education rather than solving problems. Some key elements of a tutorial pattern are as follows:

  • Introduction/Learning goals - States what the user will accomplish in the tutorial.
  • Prerequisites - Lists required knowledge/tools.
  • Step-by-step instructions - Provides hands-on exercises and activities.
  • Recap - Summarizes key lessons and takeaways.
  • Assessment - Questions or exercises to check understanding.
  • Next steps - Points to additional resources for more learning.

This clear rhetorical pattern serves the unique goal of building skills interactively. The lesson shape provides scaffolding and direction ideal for beginners.

(By the way, I’m not sure why “tutorials” isn’t an information type in DITA. The tutorial fills an important niche for learning content in technical communication. Maybe the DITA specification group felt that tasks include tutorials.)

Information patterns in explanation content

In Diátaxis, explanation content provides background and context to illuminate a concept. The goal is deeper understanding rather than problem solving. The following are some common elements of the explanation pattern:

  • Introduction - States the purpose and previews the discussion.
  • Definition - Formal definition of the concept.
  • Background - Provides history and context.
  • Details - Elaborates on various aspects of the concept.
  • Visuals - Diagrams, illustrations, examples that clarify.
  • Relationships - Connects concepts to other ideas and approaches.
  • Implications - Explores effects, outcomes, and significance.
  • Summary - Recaps the key points about the concept.
  • Further Reading - Additional resources to learn more.

This rhetorical structure moves from overview to specifics in order to paint a rich picture of a topic. The goal is synthesizing disparate details into a cohesive narrative about the concept.

Information patterns in reference

In the Diátaxis approach, reference content follows its own distinct pattern serving a dedicated purpose. Procida states, “Reference guides are technical descriptions of the machinery and how to operate it.”

Whereas tutorials focus on learning, reference focuses on factual details about a product or system. Some hallmarks of the reference pattern are:

  • Overviews - High-level summaries of a component’s purpose and capabilities.
  • Specifications - Precise technical details of inputs, outputs, configurations, etc.
  • Options - Charts comparing different options or versions.
  • Parameters - Lists defining all available parameters and their usage.
  • Code samples - Snippets demonstrating implementation and usage.
  • Visuals - Diagrams illustrating technical concepts and relationships.

The reference pattern emphasizes comprehensive, accurate information presentation. The goal is precise and authoritative descriptions users can consult to understand the machinery while working with it.

Information patterns in how-to guides

In Diataxis, how-to guides follow a recipe-like shape focused on solving real-world problems. How-to guides help readers work their way through a problem-field.

Whereas reference provides technical details, how-to guides show practical application. For example, see this topic from the Django documentation: How to configure and use logging.

Some common elements of the how-to pattern include:

  • Prerequisites - Required knowledge or conditions to solve the problem.
  • Intro - If needed, a more detailed description of what the guide will cover.
  • Ordered steps - Sequential instructions to solve the problem, to the extent that’s possible.
  • Visuals - Diagrams and illustrations supporting the steps.
  • Examples - Specific use cases demonstrating the problem and solution.
  • Variations - How the steps may differ under certain conditions.
  • Recap - Summary of what was accomplished.
  • Related links - Pointers to other related procedures.

This structured pattern provides problem-solving assistance distinct from conceptual information. The goal is unambiguous guidance users can follow to solve a particular problem.

Objections about separating content by type

In learning about Diátaxis, I was concerned about the separation of content into distinct groups. Siloing documentation into tutorials, how-tos, reference, and explanation seemed overly opinionated and arbitrary as an information model. What research was this information model based on?

I reached out to Daniele on the #diataxis WTD Slack channel, and he clarified that Diátaxis isn’t meant to impose four rigid buckets that content must squeeze into. Rather, it’s an analytical approach that emerges from identifying four core user needs. In other words, when you identify the user’s information needs, these four fundamental types of documentation arise from those needs: tutorials, explanation, references, and how-to guides.

He acknowledges the critique that people don’t strictly separate these modes, but says that documentation itself should still be clear about its purpose and stabilize around meeting specific user needs.

So the core argument is:

  • Users have different needs from docs.
  • These needs can be mapped to 4 categories.
  • If you write according to those needs, patterns will start to emerge, and …

Thus, 4 types of documentation naturally form to serve those needs.

This model may oversimplify things, but the 4 Diataxis types are still useful as an abstract approach for thinking about docs, even if divisions aren’t absolute in practice.

Experiments at work

In my documentation at work, I recently separated out some concepts by type. For example, when working on reference materials for map data concepts, I initially had conceptual explanations scattered throughout the docs. This made it hard for users to find the conceptual information they needed.

So I decided to group all the conceptual topics into a central “Map Data Concepts” section — like a Wikipedia for map terms and concepts. This created a reliable one-stop shop for reference on key concepts. I now have a space to continue adding more concepts, and I don’t have to worry about reusing similar concepts in different API overviews.

Although I was initially reluctant to separate out concepts from the API overviews, this turned out to be a good move. Both conceptual definitions and overviews probably fit under “Explanation,” but even more granular separation of content by different explanation types seemed helpful.


All-in-one platform to create, share, and manage your documentation

Clear technical documentation, complex translation, and content operations

Will information organization still be necessary when users interface with docs through AI tools?

At this point, note that I’m steering away from explanations of Diátaxis and introducing my own ideas.

With the rise of AI, I think the information architecture of help content may become less critical in the future. Most users will likely interface with documentation primarily through chatbots and other AI tools rather than navigating a complex help system. I wrote about this in AI chat interfaces could become the primary user interface to read documentation

In a way, this reduces the need to obsess over the perfect organizational schema. ChatGPT, Claude, and other AI agents can deliver hyper-personalized help on demand, without requiring the user to know where some piece of information lives in the docs. The AI interface essentially abstracts away the information architecture or pattern and just surfaces the most relevant content dynamically. This makes the documentation’s organization less important from a user perspective.

That said, the actual documentation source still needs to be well-structured for the AI to “learn” from it effectively. But the end user probably won’t care as much, if the AI delivers the right information to them directly.

How can information patterns be used with AI prompting techniques?

In the context of AI, there’s another major benefit to the Diátaxis information model. You can more easily create structured prompts that ask an AI to sort and arrange unstructured information into specific information patterns. I wrote about this in Use cases for AI: Arrange content into information type patterns.

Let’s say that you gather a large body of content about the Widget API from internal documents, code, threads, and more. You can then supply this corpus of unstructured content to an AI and ask it to arrange the relevant information into an information template like this:

{Intro}

{Prerequisites}

{Problem to solve}

{Ordered steps}

{Substeps}

{Examples}

{Expected outcome}

{Related links}

You could even include descriptions of each template section. The AI tool will then pick out the relevant information from the large body of material and arrange it into the pattern you defined. This can significantly speed time to a first draft.

Conclusion

In conclusion, should you be using Diátaxis? Even if you don’t separate content by type, defining and shaping content into these four content types might help improve your documentation. It’s an easy-to-understand approach to documentation that draws power and appeal from this simplicity. You can learn more at https://diataxis.fr.

Related resources

See this BrightTALK video Introducing the Diátaxis Approach to Technical Documentation.

I wrote this post with some AI assistance.