"AI tools are moving the floor up. There’s more being expected of writers and I worry that junior roles, just like they are in engineering, are going away.

The basis of the craft is changing. Being a good writer, whatever the field, takes time and training. It’s a field of instruction, pedagogy, information stewardship. It’s part marketing, education, support, and engineering. By definition, it is different from being an engineer, but now that market is demanding both roles in one. This is a new, demanding environment and market.

I think we need to think very differently about what a technical writer role is and pivot accordingly. I’ve seen many people writing about AI tools, and yes, that’s great. But there is a huge opportunity for us to think bigger about this role and at a top level: What does a full stack docs strategy (and yes here are some AI tools to help build that). What does it mean to help build a unified data model for APIs? What information architectures do different docs portals need and how can we implement front-ends to maximize that structure for the best-in-class user experiences (leverage AI accordingly)? DocsX (docs experience) now has to be considered a full stack problem. So let’s get to it."

https://medium.com/@anandi.silva.knuppel/the-engineering-of-the-technical-writer-89092b609cf0

#TechnicalWriting #AI #GenerativeAI #TechnicalCommunication #DocumentationEngineer #DocsX #FullStack #SoftwareDocumentation

"Over the past few months, I’ve been talking with folks about how they find information and learn about a product. ChatGPT and Claude and Gemini (or at least Google’s “AI overview”) are consistently mentioned as one of the main methods people use. Even if the output isn’t that reliable, visiting an AI tool is still a key part of the information-finding flow.

AI tools are used for all sorts of information-finding flows:

- Answering basic questions about how to accomplish a task.
- Decipher the potential root cause of an error message and provide next steps for resolution.
- Provide solutions to intricate application design questions.
- Suggest syntax for code, a formula, or a SQL statement.

You need an AI strategy for your documentation to enable customers using AI to be more successful when using your product to accomplish their goals.

The components of an effective AI strategy include the following:

- Develop: Partner with teams building AI into your product.
- Discover: Evaluate and improve your content and content strategy.
- Measure: Measure how people use AI to interact with your documentation.
- Adapt: Explore use cases for AI in your documentation practice."

https://thisisimportant.net/posts/ai-strategy-for-documentation/

#AI #GenerativeAI #Chatbots #AIAgents #TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #ContentStrategy

Designing Complex Systems: Enterprise, Heavy Data, and AI https://leanpub.com/designingcomplexsystems by Gideon Adeyemi is the featured book on the Leanpub homepage! https://leanpub.com #ComputerProgramming #GraphDesign #Graphics #Software #TechnicalCommunication

Find it on Leanpub!

"The success of any AI initiative in technical communication depends on how responsibly it is applied. The workflows described so far – drafting, revision, and quality assurance – can all deliver real benefits, but only when guided by principles that protect clarity, accuracy, and accountability. Without those guardrails, AI becomes another source of noise rather than a tool for improvement.

The first principle is clarity. AI should never obscure meaning or introduce unnecessary complexity. Writers must always verify that generated or revised content still serves its audience and that explanations remain specific and concrete. A perfectly grammatical sentence that confuses readers is not an improvement.

The second principle is accuracy. AI systems cannot verify facts or interpret technical details with the precision of a subject matter expert. Any information produced or edited by a model must be checked against source materials and validated through established review channels. This step is not optional.

The third principle is accountability. Human writers and editors remain responsible for the content they publish, regardless of how it was created. That responsibility extends to ethical and legal considerations such as data privacy, bias mitigation, and compliance with organizational standards. Every AI-driven workflow should include clear documentation of how the system was used and who approved the results.

The final principle is transparency. Teams should share their AI practices openly within their organizations. This builds trust with stakeholders and prevents misuse born of misunderstanding. When people know what AI is doing and why, they are more likely to support its use.

Responsible adoption is what separates innovation from recklessness. The goal is not to prove that AI can write or edit, but to show that humans can use it wisely."

https://www.tcworld.info/e-magazine/technical-writing/why-ai-wont-replace-tech-writers-but-will-reshape-their-work

#AI #GenerativeAI #TechnicalWriting #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

This week's Featured Links post links to articles about how Putin outsmarted the oil sanctions, how Charlie Angus is still haunted by the Edmund Fitzgerald sinking, how the Florentine diamond resurfaced after 100 years in hiding, and more.

https://coredump3.blogspot.com/2025/11/featured-links-november-11-2025.html

#GoogleDocs, #History, #Medical, #MicrosoftWord, #Movies #TV, #Politics, #SFF, #Software, #TechnicalCommunication, #Vision

Jetzt muss ich leider das Politische mit der Arbeit mischen. Bin wieder auf der #tekomjahrestagung und gleich der erste Vortrag war so gut, dass ich jetzt schon wieder fahren könnte. Bleibe trotzdem bis Donnerstag. ☺️

#tekom #tcworld #technicalcommunication

"Most of the evidence today, anecdotally and in practice, suggests that technical writing as a field will remain viable. At the same time, it is clear that GAI will directly impact the work of technical writers. It is also clear that trying to ignore or downplay the presence of GAI (even with the best of intentions) will not change that fact. The best, most evidence-informed suggestion I can make for technical writers is to learn more about GAI, how you can incorporate it into a work process that is still distinctly human, how you can effectively advocate for those adjustments with influencers and decision makers, and how you can center yourself as someone who has a unique knowledge-based skillset and a highly evolved understanding of context."

https://idratherbewriting.com/blog/gen-ai-techcomm-evolving-future

#AI #GenerativeAI #TechnicalWriting #TechnicalCommunication #SoftwareDocumentation

"I really enjoyed speaking at Write the Docs Berlin this year. My talk was a bit special, a message in a bottle for writers who are struggling — for anyone who’s struggling in their careers, really. Here are the recording and the slides, as well as some links to the content that inspired the talk. I hope you’ll find it useful."

https://passo.uno/failing-well-wtd-berlin-2025/

#TechnicalWriting #SoftwareDocumentation #TechnicalCommunication

This one is a must-see for all technical writers and technical communicators alike!!

"In this conversational podcast, Fabrizio Ferri Benedetti (Passo.uno) and I talk about the impact of AI on the technical writing profession. We tackle the anxiety, seen and felt almost everywhere, but especially on Reddit, within the community about job security and analyze the evolution of the technical writer's role into a more strategic context curator or content director. We also cover practical applications of AI, such as using agents markdown files to guide language models (with style overrides or API reference contexts), and the role documentation plays in improving AI's outputs (Fabri's phrase AI must RTFM)."

https://idratherbewriting.com/blog/podcast-fabri-tom-sept-episode-1

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

"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

"Since the appearance of LLMs, writers have been concerned with AI disrupting our craft or making it disappear. In a recent post, a user asks “How do I pivot to a career path that won’t revolve around AI”. One of the answers, in typical Reddit style, recommends becoming a welder. Another compares the original poster with an encyclopedia’s salesmen, anchored in anachronistic ideals.

My answer is that no, we’re not going to disappear, because LLMs will always suck at what makes us indispensable. Instead, we’re going to shift to roles that are more editorial and grounded in strategy and coding than in writing, which isn’t the most important part of our job anyway. Start experimenting with AI right now, because the future of most intellectual work is augmentation. If you let businesses own the narrative around docs and AI, you’ll be left out of the picture. If the thought of using AI disgusts you, you might be humanizing it: Think of it as just a tool."

https://passo.uno/tech-writing-optimism-reddit/

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

It's not very often that GPT5 surprises me. In fact, I would say it's quite rare when compared to Gemini 2.5 Pro. But this time, it really, really surprised.

I asked the LLM if it could provide me a list of tools, technologies, and platforms used for documenting software, ordered from a less "docs-as-code" approach to a more documentation-based approach were docs are seen as product. I also noted that this list should also represent the level of technological autonomy provided by each tool - from less to more autonomous.

The output left me really astonished, in the sense that's perfectly accurate and spot on:

#TechnicalWriting #DocsAsCode #TechnicalDocumentation #SoftwareDocumentation #SoftwareDevelopment #TechnicalCommunication

"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

"[W]hat we are doing is shepherding AI, limiting it to certain contexts. We are learning where it’s best to call it, how is best to feed it. And what to do with the output. So is it looks very much like an editorial process, an editorial workflow where you provide some initial input, maybe some some idea on what content to produce, then you review it. There’s always that quality assurance, quality control side, the supervision.

AI is not really autonomous. It relies a lot on us. And I feel like sometimes there are days where, when coding through AIs or doing some assisted writing, I’m spending more time helping out the AI doing the actual task that I’m asking the AI to do. But I take this as a learning process. I read this article the other day, Nobody knows how to build with AI yet. And it was a developer saying that they haven’t quite figured out how to best work with AI. There were lots of comments around the fact that you have to spend lots of time, you have to learn how to talk to it, and when the model changes, you have to also maybe change something you’re doing. You have to learn how to optimize your time. But your presence is always mandatory.”

https://passo.uno/webinar-ai-tech-writing/

#TechnicalWriting #AI #GenerativeAI #LLMs #Chatbots #PromptEngineering #SoftwareDocumentation #SoftwareDevelopment #TechnicalCommunication

"While haste and speed often get confused, they differ in that the second shows control instead of panic. You can maximize speed while keeping accuracy quite high; beyond a certain point, though, spending more time on accuracy, style, or other aspects that prevent a document from going live always yields diminishing returns.

Nobody reads perfect yet outdated docs, except historians. Even then, docs aren’t perfect, because documentation can’t ever be perfect. This is a key principle I stand by (call it the Ferri Paradox if you want): Any document describing a system is necessarily inaccurate. And yet, this reality doesn’t significantly alter the impact of our work, because we aim for simplicity and usefulness over extreme faithfulness. Given how imperfect products are, docs are a charitable portrait.

Now, how you write docs quickly depends on a number of factors. Some of those factors you can’t control: your overall amount of experience as a writer, your initial expertise with specific technologies, and the way features are developed and released in your organization. But other aspects are yours to act upon. For example, you can decide how to best use the technical resources at your disposal and how to approach writing the docs and asking for feedback."

https://passo.uno/how-write-tech-docs-quickly/

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #SoftwareDevelopment #Programming #Docs #Documentation

Basic Questions That Every (Technical) Writer Should Try To Answer - AKA Technical Writing 101:

I assure you that If you can answer all of these questions, your readers won't mistake you for a chatbot :)

1. What is the purpose of the document that I'm writing?

2. Why am I writing this document?

3. Who is the target audience of this document?

4. Is this document part of a series of documents?

5. If so, have I established a nexus to the other documents in the series?

6. Are there any predefined formal requirements that the document must meet?

7. Does the document meet those requirements?

8. Does the document include an introduction?

9. Does the introduction clearly explain the purpose of the document to the target audience?

10. Does the introduction present the topics that will be explored in the body of the document in a straightforward way?

11. Does the document include a conclusion?

12. Does the conclusion provide a good summary of the previously explored topics?

13. Does the conclusion tell readers what they should have learned by following the document?

14. Does the body of the document include use case scenarios based on user personas that explain the potential advantages of adopting the explored tools or methods?

15. Does the body of the document depict real-life examples of how readers can immediately start using the tools or methods explained in the document?

#TechnicalWriting #TechnicalCommunication #Writing #Nonfiction #Documentation #Docs

"The purpose of documentation is to skill and empower someone in their craft. It serves their acquisition and application of skill.

I have heard it suggested that documentation should now be optimised for consumption by AI. That is like asking how we can make our cities better for cars, or our workplaces better for the furniture.

If creators of documentation are prepared to sacrifice its human purpose in order that LLMs can more effectively slurp it up and regurgitate it on demand, then they have meekly accepted values that more properly belong in a dystopian horror story.

Even if we think about the notion only pragmatically, leaving all values aside, it’s a panicky, inconsidered idea. What possible sense does it make to try to “write for LLMs” when LLMs themselves are evolving so rapidly that their capacities and patterns change from one week to the next?

Human beings are difficult creatures with complex needs, but they have been that kind of creature for thousands of years. Not only have we painstakingly built up deep understanding of them, we are them; we can know them from the inside. A good way of writing documentation for human beings today will still be a good way to do it in a few years’ time."

https://vurt.org/articles/my-favourite-german-word/

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

"What are docs for AI agents? How are they different than internal eng docs? Do we really have to maintain the agent docs and eng docs as separate docs sets? This page contains my notes on these questions.

Scope:

I work on developer docs i.e. docs for software engineers. I don’t know how relevant AI agents are for technical writers in other industries or domains.

I’m thinking specifically about docs for AI agents. I’m not sure that an all-encompassing “docs for AI best practices” exists. The way that we optimize docs for RAG-based chatbots (for example) is probably different than the way we optimize docs for AI agents."

https://technicalwriting.dev/ai/agents/

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #AI #GenerativeAI #AIAgents #DocsForAIAgents #Chatbots #DeveloperDocs #SoftwareDevelopment