#technicalcommunication — Public Fediverse posts

For the forseeable future, AI tools will continue to generate such incomplete and sometime hallucinated outputs that there will be a continuing need for a "human-in-the-loop" to not only use several LLMs to review each other's output but to fact-check the final output. Using one LLM alone results in mediocre quality. Using two LLMs results in (sometimes very) good quality. Use three LLMs with human verification for great/outstanding results.

"1,131 people across the documentation industry responded to the 2026 State of Docs survey — more than 2.5x the number of respondents last year. But the size of the sample matters less than what it represents: a genuine cross-section of the people who create, manage, evaluate, and depend on documentation.

Documentation’s role in purchase decisions is stable and strong, and the case that docs drive business value is well established. The shift this year is in what documentation is being asked to do, and who — and what — is consuming it.

AI has crossed the mainstream threshold for documentation, both in how docs get written and how they get consumed. Users are arriving through AI-powered search tools, coding assistants, and MCP servers. Documentation is becoming the data layer that feeds AI products, onboarding wizards, and developer tools. The teams investing in this shift are treating documentation as context infrastructure, not just a collection of pages.

But adoption has outrun governance, and the gap matters. Most teams are using AI without guidelines in place, and documentation carries a higher accuracy bar than most content. After all, one wrong instruction can break a user’s implementation and erode trust in the product.
(...)
Writers are spending less time drafting and more time fact-checking, validating, and building the context systems that make AI output worth refining."

https://www.stateofdocs.com/2026/introduction-and-demographics

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #DocsAsProduct #AI #GenerativeAI

"In my post The Emerging Picture of a Changed Profession: Cyborg Technical Writers — Augmented, Not Replaced, by AI, I mentioned an upcoming presentation I'm giving to students and faculty. I argue that the future of the profession is the cyborg model, where machines augment our capabilities rather than replace us. In this post, I share notes about what skills a tech writer would need to learn to thrive in this world of augmentation.

If you have feedback about these skills, let me know. My intent here is to demonstrate what actual skills should be emphasized for those entering the profession, or for those currently in the profession who want to get ahead with AI. Note that the following sections are mostly bullet points, in the form of notes."

https://idratherbewriting.com/blog/10-principles-of-cyborg-technical-writer

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #Documentation #AI #GenerativeAI #LLMs

Indeed, we can't allow autopilot to head into a whirlwind...

"We may be doing docs-as-code, but docs are not code. Docs run on people, and people are a messy tangle of goals, skills, and emotions. When docs hit the brain, they meet varying expectations, knowledge levels, reading abilities, and needs. None of this can be reproduced or simplified to a single pattern, but good docs use structure and words wisely to produce the best possible linguistic shape that can land safely on most people’s heads. Only humans can decide whether that message is getting across in the right way.

Getting there is a balancing act between business needs, user needs, and your own. That’s the diplomatic tension that forces all good tech writers to slow down and consider all points of view in the room as if they were in the middle of a spaghetti Western standoff. Slowing down is a deliberate, necessary act in all crafts, and tech writing is no exception. No matter how fast LLMs can churn out drafts, they don’t understand the tension in tech writing, to which we’re adding AI itself as an additional consumer of docs.
(...)
The quality of the docs I produce is still high, I was saying. That’s because I’m not letting LLMs take the steering wheel, and because I’m building new habits around them: setting up guardrails, automating what can be automated, and keeping my hands on the decisions that matter. I can do that because I know what good docs look like, and because I’ve been doing this long enough to feel when something’s off. That intuition came from years of wrestling with products and watching users struggle with pages I thought were clear. AI can help me write faster. It cannot replace the slow accumulation of judgment that tells me when to stop."

https://passo.uno/real-cost-of-documentation/

#TechnicalWriting #SoftwareDocumentation #AI #DocsAsCode #GenerativeAI #LLMs #SoftwareDevelopment #AISlop #Programming #TechnicalCommunication #Documentation

"Too often, API documentation writing is introduced as a series of rules or gut feeling about what seems obvious. Beginning writing, that’s a good approach. They’re easily understood and conform to. They’re rarely wrong. They’re far from complete, however.

API documentation writing is an art, not a science. As the artist, your influence is no less important than anyone else’s. But you’ll need to understand more in order to take the writing to a new level. You’ll need to know theory, the hows and whys, and to think like a programmer. The theory here is not only to connect with clients but also to present information in the most efficient way possible. It’s the last points that learning API documentation writing does not do well.

The following is a talk through. I talk about an element in conversational detail. I aim to discuss the important points, why an approach may be inappropriate, what the goals should be, and how to fix it. Along the way, I may make blunt statements. I do that for effect. By exposing the reason for the critique, we can get an understanding of the solution. We’ll look at this from the writer’s perspective."

https://robertdelwood.medium.com/improving-api-documentation-describing-one-parameter-at-a-time-cb53a89637a2?postPublishedType=initial

#TechnicalWriting #APIDocumentation #SoftwareDocumentation #SoftwareDevelopment #Programming #APIs #TechnicalCommunication

"Over the weekend, I spent about 10 hours working with Claude to manually validate 578 coding patterns across a range of languages and coding tasks for my Agent Skill Report. We had to deep dive into standard library docs, package-specific documentation, large enterprise docs, and personal blogs. My goal was to ensure that every API and configuration pattern I was using in a behavioral evaluation experiment reflected the current guidance from official sources. My learnings about agent docs access patterns were secondary to this project, but the results are a rich treasure trove of data that may inform how I use agents with docs in the future. As a technical writer who has worked on SaaS and developer docs for the last decade, honestly, my findings made me a little sad.
(...)
My high-level takeaway was this: I expected an agent to try to use docs like I do, and was very surprised when it didn’t.
(...)
Over the course of validating 578 patterns across 20 different skills, my agent and I built up a pretty comprehensive picture of what documentation access patterns actually work for agents, and which ones don’t. I had my agent keep a running reference doc of its learnings, and by the end of the project, the patterns were clear enough to categorize."

https://dacharycarey.com/2026/02/18/agent-friendly-docs/

#TechnicalWriting #TechnicalCommunication #AI #AIAgents #LLMs #Chatbots #AgenticAI #SoftwareDocumentation #APIs #Docs #Documentation

"When we write documentation, we often assume someone will read it top to bottom. Even when we skim, we start at the top, absorb context, build a mental model. And we infer stuff, like if you’re reading design system docs, you probably already know what a design system is.

AI agents don’t work like this. They retrieve the most relevant chunk based on semantic similarity and produce a response from that slice. If the definition is three paragraphs in and the agent retrieves paragraph one, it fills in the gaps.

That’s where hallucination creeps in. You’re absolutely right! Not because the model is careless, but because much of our documentation is structured for narrative flow, not retrieval. It was always fragile, humans were just good at compensating.

Writing for AI agents accidentally makes documentation more accessible. A screen reader user navigating by headings needs the same explicitness an AI agent needs. A new team member needs definitions that don’t assume prior knowledge. A developer working in a second language needs sentences that say exactly what they mean. Explicitness helps anyone who can’t rely on context to fill gaps.

Look at well-documented APIs. The ones that specify exactly what parameters do, what they return, what breaks. They’re used more, trusted more, cause fewer support tickets. Explicitness scales."

https://gerireid.com/blog/ai-is-accidently-making-documentation-accessible/

#TechnicalWriting #Acessibility #TechnicalCommunication #AI #SoftwareDocumentation #AIAgents #APIDocumentation #Markdown

"The secret of how tech writers develop trustworthy information is that they practice genuine care for the end-to-end experience, learn the product experience inside and out (even if they start as an outsider), and build context that you can’t just get from writing.

This is “earned” context through building trust across other teams and stakeholders and through shipping successful (and unsuccessful) products in different environments and working cultures.

Tech writers (or whatever they’re called these days) are paid to develop (and maintain) trustworthy information, not just move it around. Automation can help with maintaining trustworthy information but it’s not all that technical writers do.

Earning or developing context well also takes real skills and demands a certain kind of character.

Skills & traits for developing trustworthy information

- Asking the right questions in the right way in the right place and at the right time. It’s no accident that some of the best technical writers I’ve worked with used to work as journalists.
- Constantly tracking what you know and don’t know with intellectual humility and rigor (Stay tuned for my future “Assumption Tracker app!”)
- Facilitating discussions to help surface internal confusion, misalignments, and other kinds of conversation debt
- Evaluating the trustworthiness of information
- Evaluating what others know, what product language world they live in, and what they don’t know
- Intellectual humility, honesty, and rigor"

https://jessicacanepa.com/blog/developing-trustworthy-information/

#TechnicalWriting #SoftwareDocumentation #TechnicalCommunication #SoftwareDevelopment #APIDocumentation #Automation

💯 👉 "When you say "docs", you're careful to focus on the output, omitting the process. Perhaps you don't know how docs are produced. You've forgotten, or perhaps never knew, that docs are product truth; that without them, software becomes unusable, because software is never done, is never obvious, and is never simple. Producing those docs requires tech writers.

Tech writers go to great lengths to get the information they need. They write so that your audience can understand. They hunger for clarity and meaning and impact. They power through weeks full of deadlines, chasing product news, because without their reporting, most products wouldn't thrive; some wouldn't even exist. The documentation they produce is not a byproduct of development: it's the glue that ties the product together.

An LLM can't do all that, because it can't feel the pain of your users. It can't put itself into their shoes. It lacks the kind of empathy that's behind great help content. It does not, in fact, have any empathy at all, because it cannot care. You need folks who will care, because content is a hairy beast that can only be tamed by agents made of flesh and capable of emotions: humans." 👈 💯

https://passo.uno/reconsider/

#TechnicalWriting #AI #SoftwareDocumentation #TechnicalCommunication #GenerativeAI #LLMs #Docs #Documentation #SoftwareDevelopment

"This article examines several more common problems occurring in API documentation. They are easily prevented or have simple workarounds but the writer must be aware of them in the first place. These underscore the importance of:

- Writers being familiar with programming and development concepts, so that,
- Writers can think like developers. Only by thinking like a developer can writers then hone in on client’s nuances, customize the developer experience, and optimize the time in the documentation. The goal is an ironic one. We want documentation so good and clear that clients don’t even have to read it. You’ll see what I mean in a moment.

The striking thing about these is how simple they seem. So much so, they are often overlooked. Afterall, how much can be said about an offset value of a returned list, or sorting? As it turns out, plenty. Thinking like developer is encompassing. Enough information must be presented so that clients know ahead of time what the field or endpoint does, returns, what the behavior is, and what each parameter does. You have to anticipate questions and understand how clients think about things. The last thing we writers want for clients is to make them experiment with values and guess outcomes. That annoys them and wastes their time. It means we didn’t do our job.

API documentation is not technical writing. It’s API documentation writing. The key differences are the dependence on code and a deep understanding of development practices. There are countless nuances and subtleties — and each one matters to developers. How can it not? You’re writing to developers about development. It needs to be precise and it needs to speak their language."

https://robertdelwood.medium.com/more-common-api-documentation-errors-26f1a8ceaaec

#APIs #APIDocumentation #TechnicalWriting #Programming #SoftwareDevelopment #TechnicalCommunication

Yep, DITA XML is still rocking in the technical communication world and technical writers need to have at least some familiarity with the topic.

https://learningdita.com/pluginfile.php/1/tool_certificate/issues/1762964073/6088999983MC.pdf

#DITA #DITAXML #TechnicalWriting #TechnicalCommunication #StructuredWriting

"Finally, I haven’t even pitched the strongest argument for why technical writers and documentation will continue to be relevant in the future: AI tools are terrible without good documentation. In the same way that you need valid, accurate context when using AI tools to create documentation, AI tools need an accurate body of documentation to produce useful, hallucination-free outputs. Informal tests by my colleagues show that AI outputs improve by orders of magnitude when trained on more abundant and accurate documentation.
(...)
In other words, technical writers will create and package information specifically for AI consumption, ensuring the AI has the necessary context to produce accurate and relevant results.

There’s a sales motive for keeping technical writers around, too. Let’s say an external developer needs to create, say, a mapping application for their project, and they decide they need routing logic. Following a vibecoding approach, they integrate your company’s MCP server into their IDE and tell their AI tool to create an app that draws routes from one point to another. If the AI tool can successfully fulfill the developer’s needs, requiring only that they provide an API key (which then initiates billing), the company that has provided this solution will sell more API services. No one wants to fiddle and fuss with hard-to-configure technology that doesn’t work, and by hard-to-configure, I mean APIs that require manual configuration rather than APIs you can configure with natural language."

https://idratherbewriting.com/blog/strategies-to-succeed-in-context-of-ai

#TechnicalWriting #TechnicalCommunication #AI #GenerativeAI #SoftwareDocumentation ##SoftwareDevelopment #APIDocumentation

"Errors in content, especially technical documentation, lead to mistrust. When you write a piece of content, consider the future of the content.

The future of the content depends on the purpose and type of content that you’re writing. This list contains some common expectations that readers might have about various content types:

- A blog post has a date stamp and isn’t kept continually updated.

- Technical documentation always matches the product version that it references.

- Architecture documents reflect the current state of the microservice architecture.

- An email gets the point across and can’t be edited after you send it.

You must consider the future and maintenance of any content that you write if your readers expect it to be kept up-to-date. To figure out how difficult maintaining your content will be, you can ask yourself these questions:

- How frequently does the thing I’m writing about change?

- How reliable does my content need to be?

- How quickly does my content need to be accurate (e.g., after a product release)?

By answering these questions, you can then make decisions about how you write your content.

- What level of detail will you include in your content?

- Will you focus your efforts on accuracy, speed, or content coverage?

- Do you want to include high-fidelity screenshots, gifs, or complex diagrams?

- Do you want to automate any part of your content creation?

- Who will review your content? How quickly and thoroughly will they review it?"

https://thisisimportant.net/posts/how-can-i-get-better-at-writing/

#TechnicalWriting #TechnicalCommunication #ProfessionalWriting #SoftwareDocumentation #InformationArchitecture

"API documentation writers don’t just write content. We’re liaisons between client developers and in-house developers. I often say “we’re paid by the company but work for our clients.” Many think that in-house developers automatically empathize with the client developers. After all, they’re all developers, right? Right? Well, no. A surprising number of times, in-house developers are actually out of touch with clients. Why else would we be talking about having clear field names? They get tunnel vision or become myopic while in the code. This is not unique to developers. All professions have this risk. That’s our job to make sure that clarity is there for the clients. We can’t do it completely by ourselves. We need developer’s buy in. That means, one of two things.

We can push back on the in-house developers. When we see a meaningless, poor, or bad field names, for example, we have the right, if not obligation, to get it changed. Some developers may disagree. That’s OK. The truth is, the code doesn’t belong exclusively to in-house developers. It’s the client’s code. They’re the ones intended to run the code, to know which fields to pass in, with which values, and to read the response JSON. That makes it our code, too. We not only have to run the code but also to explain this to clients. We have a say in the matter."

https://robertdelwood.medium.com/writing-for-humans-an-api-documentation-writer-writes-3c51a6ea87a5

#TechnicalWriting #APIs #API #APIDocumentation #SoftwareDevelopment #APIs #TechnicalCommunication

"Let me be blunt.

If your startup offers APIs and you don’t have a portal, you’re lighting developer acquisition money on fire. 💵 🧯🚒

Here’s what a good portal actually does:

Shortens time-to-value: faster POCs, faster adoption.

Reduces support tickets: devs can find what they need.

Builds trust: your API feels stable, documented, and ready.

Increases conversion: when docs show how easy it is to integrate, not just tell.

Still sending PDF onboarding packets to partners?

C’mon, boo. 🥲"

https://www.quetzalliwrites.com/newsletters/developer-portals-dev-friendly-or-dev-frustrating

#DevPortals #DeveloperPortals #APIs #API #APIDocumentation #TechnicalWriter #TechnicalCommunication

"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.

Here is some more context to help you decide on an approach and get started."

https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299

#API #APIs #APIDesign #REST #APIDocumentation #OpenAPI #DocsAsCode #TechnicalWriting #TechnicalCommunication

"No one’s heard of a starving craftsman, just starving artists, and for a reason. Craftsmen create something people need. You’ve mastered a few important skills and moved up in the company. The important aspect here is that as you reach out to a greater community, you realize that there are plenty of people who are more skilled than you and who are still learning. Learn from them.

Gaining textbook skills or collecting certifications isn’t the point anymore; it’s applying all this knowledge in practical ways. Along the journey, you need to watch out for your best career interests and make sure that what you’re doing is what you want to do. For example, many get lost in promotions that lure them away from what they like doing, whether that’s programming or writing.

Finally, don’t underestimate perpetual learning. This is the key to the long road. Take time to practice, even if your job doesn’t seem to allow it. Learn new skills or apply existing skills in new ways. Along with practice comes failure, but don’t let that discourage you."

https://robertdelwood.medium.com/book-review-apprenticeship-patterns-guidance-for-the-aspiring-software-craftsman-808c95ee478e

#Craftsmanship #Craftsman #TechnicalWriting #SoftwareDevelopment #Programming #TechnicalCommunication

"[T]o build effective docs you not only need tools and content types, but also a model of needs that documentation must satisfy as a product, or of actions users need to accomplish through docs. This model should be fairly independent from the type of software product you’re documenting, in the same way conceptual models of product design and satisfaction abstract away the specifics. Aiming for a general model is necessary because it helps professionals learn and communicate together.
What follows is my own descriptive model of user needs for documentation, one I’m following to build and arrange documentation today.
The approach I’m proposing here is a model of what user actions the docs are meant to satisfy. The model aims at connecting both UX research and documentation frameworks with a conceptual and functional layer that focuses on two aspects: docs as a product and what users are meant to accomplish through them. It’s an attempt at describing what technical documentation should do. It’s treating docs as a product that someone is going to use to achieve actual goals.
As I said, the core of the model is actions. I’ve identified seven that I think cover a decent amount of goals that a consumer of docs may want to accomplish when using documentation. They represent common patterns in how users interact with documentation across different products and domains. They’re the following, each bearing an alternative term in parentheses: Appraise (Discern), Understand (Learn), Explore (Discover), Practice (Train), Remember (Recall), Develop (Integrate), and Troubleshoot (Solve)."

https://passo.uno/seven-action-model/

#TechnicalWriting #Documentation #TechnicalCommunication #UX #DocumentationFrameworks #UXResearch #DocsAsProduct

"Similar to Wood’s conviction that AI’s transformative potential doesn’t come from simple tasks like writing emails, tech writers will likely find conviction when they go beyond fixing simple grammar errors to using AI for developing conceptual articles, generating release notes, or understanding connections across disparate API products.

One of my colleagues compared using AI like learning to play an instrument—it’s one thing to have an intellectual understanding about the instrument and notes, but knowing how to play an instrument well is entirely different. It takes practice, experimentation, learning, diligence, and time. Maybe too many tech writers feel that AI should provide a push-button solution to creating documentation effortlessly (a misguided perception based on too much AI hype). When pushing that button doesn’t magically produce great docs, perhaps they become cynical and dismissive?"

https://idratherbewriting.com/blog/trends-predictions-2025-tech-comm

#AI #GenerativeAI #TechnicalWriting #TechnicalCommunication #APIs #APIDocumentation #PromptEngineering #TechComm

Well designed information is clear, unambiguous, and enhances comprehension and other human performance.

The illustration below shows a duration. Several design changes could each have made this usable, such as adding a space:
23:00 09:30
or a word:
23:00 to 09:30

#InformationDesign #ContentDesign #TechComm #TechnicalCommunication #interface #usability #duration #time #clarity #comprehension #accuracy #performance #UserPerformance