"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

This distinction is key. Only human beings can assign a purpose to a text. And only other human beings can understand that purpose. Purposeless, meaningless texts are external to this world. Perhaps in five thousand years, there will be entities capable of assimilating automatically generated texts in order to produce something entirely new of their own free will. Until then, writing and reading will only make sense when referring to human beings as the subjects.

"Simply put, AI may understand the act of writing, in a very limited way, but it does not understand the act of reading what has been written. As someone who has read and edited literally tens of thousands of pages of technical documentation, and thousands of pages of student essays during my career in higher ed, I can tell you that there are good writers, okay writers, and terrible writers. What distinguishes them is those who understand reading as a cognitive act that is intended to produce an effect in the mind of the reader, and those who don’t."

https://www.linkedin.com/pulse/limitations-ai-writing-kai-alvason-phd-8ig0c/

#AI #GenerativeAI #Writing #Reading #Documentation #Docs #SoftwareDocumentation #TechnicalWriting

Seems legit... I've started to use it and it has been a great help when browsing a huge Git repository Vs doing the same over OxigenXML.

"DitaCraft is a lightweight extension that brings DITA support directly into VS Code, one of the most popular code editors. It provides:

- Syntax highlighting for .dita, .ditamap, and .bookmap files.
Real-time validation against DITA 1.3 standards.
- Seamless integration with DITA-OT for multi-format publishing (HTML5, PDF, EPUB, and more).
- Smart navigation, live preview, and 21 code snippets to generate bookmap, ditamap,topic templates.

Whether you’re a technical writer, developer, or student, DitaCraft helps you focus on learning DITA — without the complexity.
(...)
Who Is DitaCraft For?

- Beginners who want to learn DITA without the complexity of professional tools.

- Developers who need a lightweight DITA editor integrated into VS Code.

- Students exploring structured authoring and technical documentation.

- Technical writers who want a free, open-source alternative for quick edits and validation.

The Future of DitaCraft

DitaCraft is an ongoing project, and I welcome contributions from the community! Whether you’re a DITA expert or a beginner, your feedback and ideas can help shape the future of this tool.

Try DitaCraft today and simplify your DITA journey! 🔗 Install DitaCraft from the VS Code Marketplace"

https://medium.com/@jyjeanne/ditacraft-a-beginner-friendly-vs-code-extension-for-dita-authoring-and-publishing-13de279b69e5

#DITA #DITAXML #XML #VSCode #VisualStudioCode #StructuredWriting #TechnicalWriting #DitaCraft

@stevencudahy #mastoprompt
-Ruin

The shell of past lives,
Echo mourning choughs laments,
Of wrack and ruin,

#Haiku #SmallPoems #TechnicalWriting

"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

I just recently noticed that there are not many in-depth resources about SDK documentation for technical writers. I think this presentation provides a good "no frills" overview of the topic:

"SDK docs written by developers tend to be implementer oriented, not user oriented. That makes sense, since it's the implementers writing them. Unfortunately, this approach leads to some frustrating SDK reference manual experiences for users. The implementer-oriented doc writer tends to answer, "What is this built on?" As a user, I need docs that tell me, "What can I build with this?"

I provide examples of common SDK docs pitfalls, then present the approach that I used updating the SDK documentation that our developers had created. My goal was to give users of those docs a quick, enjoyable, user-oriented experience. To do so, I identified the likely use cases, or flows, of our product. I then grouped all entities (classes, functions, etc.) of the docs into these flows. For each flow, I arranged the entities in "flow order".

Having mapped out our codebase in this way, I was ready to begin adding content by following these principles:

1) In the leading lines, answer: what is this for? 2) Always link to the previous and next items in all flows and add "See Also" links. 3) Add a code example that demonstrates this entity's role in the flow. 4) Call out gotchas that are likely to get in the user's way when trying to use a flow."

https://www.writethedocs.org/videos/portland/2019/sdk-reference-manuals-a-flow-based-approach-chris-bush/

#TechnicalWriting #SoftwareDocumentation #SDKs #SDKDocumentation

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

"As agentic assistants get more capable, I’m seeing more emphasis on long-running tasks. These are tasks that require less human intervention and give more autonomy to the agents to make decisions along the way to achieve the task’s goal. In some ways, it seems like a primary activity for future tech comm work might involve carefully crafting long-running prompts that allow a technical writer to fully automate a task. The tech writer’s role then becomes focusing on designing prompts, instructions, and skills that highly capable autonomous agents can follow to complete the doc-related tasks. The more complex the task, the more complex the prompt.

However, I think this idea seems appealing in theory only. In reality, long-running tasks have limited application and aren’t representative of 90% of the documentation tasks I do. Most documentation tasks involve iterative decision-making along the way based on feedback loops. Although many people would like tech writers to automate their tasks, the reality is that most doc scenarios are one-offs and not repeatable in a prompt that would apply to future doc tasks.

Based on the need for the human-in-the-loop to steer, provide feedback, course correct, and apply judgment all along the way of a process—in constant conversation with an AI agent acting as a thought partner rather than a wholly autonomous agent—I don’t foresee long-running tasks being all that important for tech comm work."

https://idratherbewriting.com/blog/collaborative-thought-partner-not-autonomous

#TechnicalWriting #SoftwareDocumentation #AI #GenerativeAI #AIAgents #AgenticAI #HumanInTheLoop #LLMs

"Technical writers have survived technological changes for decades. The advent of AI shouldn’t be different. If this reminds you of Realpolitik, you wouldn’t be wrong: LLM-generated contributions are already happening and there’s no going back. Writing an AI & Docs policy means taking full ownership of the process and reminding folks that documentation requires expertise and has high quality standards. That kind of strategic thinking is what will keep us afloat.

What I would find dangerous for technical writing right now is sitting on our hands, hoping that someone else sets the rules of the game. We can’t pretend that this will sort it out on its own, so start drafting your policy, your stance, and iterate as you learn more. Your policy will also act as a reminder of the value you bring to the organization. Worst case scenario, it’ll open useful internal debates that you might have missed otherwise. We need that depth."

https://passo.uno/ai-docs-policy-contributions/

#AI #GenerativeAI #AIPolicy #TechnicalWriting #SoftwareDocumentation #DocsAsTests #LLMs

Learn to write technical specs that get shipped. Practical guide covering problem statements, buy-in, implementation plans, and spec-driven development. https://hackernoon.com/how-to-write-technical-specs-that-actually-ship #technicalwriting

"Stubblebine argues that writing is about thinking, and smart people like to think. So writing isn’t going away because of AI. As he put it, “I am always confused … when people worry about the future of writing. So let me just start with first principles, right? Like writing is thinking and smart people like to think — that’s not going away” (10:24). As long as there are smart people who like to think, they’ll continue to write.

(...)

I agree 100% about writing as a mode of thinking, which is why I’ve sort of abandoned many attempts to use AI in writing blog posts. It’s not so much that AI-generated content in posts is soulless or too bland or too general; it’s that it can sometimes remove the thinking elements of the writing process. That’s the real value of writing — the clarity of mind and changed perspective that often results.

Kantrowitz agrees, saying “that idea of going from something that you think you know and then you start writing it and you realize you don’t really know it at all. There’s great value in trying to connect those ideas on the page” (12:45). Writing forces you to sort and organize the thoughts in your mind in a way that requires clarity, and this often prompts you to review or re-investigate the subject to make sure you understand it. As technical writers, we know this. You can’t explain a complex technical concept if you don’t have a fairly good grasp of it yourself."

https://idratherbewriting.com/blog/stubblebine-how-ai-is-changing-writing

#AI #GenerativeAI #Writing #Blogging #TechnicalWriting

"For our technical writing teams, the velocity of Google Cloud's development presents two core problems: how do we keep pace with documenting new features and capabilities, and how do we ensure the existing documentation remains accurate?

To accelerate the creation process, we have integrated Gemini directly into our writers' authoring environments. This acts as a productivity multiplier, streamlining common tasks like generating formatted tables from unstructured content, translating between markup languages, and applying complex style guides with a single click. More significantly, the adoption of AI solutions enables writers to focus their time on strategic documentation solutions and ensure high quality content.

Just as important as creation is validation. For years, automated regression testing has been a staple for catching bugs in code. We are now bringing that same discipline to documentation—a goal that was long considered a dream due to the ambiguity of natural language. For our quickstarts, we use Gemini to read the procedural steps and automatically generate web orchestration scripts (using frameworks like Playwright). These scripts then execute the steps in a real Google Cloud environment, automatically verifying that our documentation accurately reflects the product's behavior. We run over 100 of these tests daily, ensuring our quickstarts are continuously validated and that you can trust the steps you're following."

https://cloud.google.com/blog/topics/developers-practitioners/smarter-authoring-better-code-how-ai-is-reshaping-google-clouds-developer-experience

#TechnicalWriting #AI #GenerativeAI #GoogleCloud #SoftwareDocumentation #APIDocumentation

"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

Looks like WriteTheDocs published their Berlin 2025 conference recently:

https://www.youtube.com/playlist?list=PLZAeFn6dfHpkP1wAM5OIqAMH4guScopET

Not to forget the previous Portland 2025 event:

https://www.youtube.com/playlist?list=PLZAeFn6dfHplMbtJtidqFFtL7rt3ASNSR

#WriteTheDocs #Documentation #SoftwareDocumentation #TechnicalWriting

"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

Spot on!! Like most technologies, AI is "just" another accelerator.

"To recap my argument, yes, AI can accelerate our output, but it won’t liberate us. AI is accelerating everyone’s output. Not just you and your colleagues’ output. It’s accelerating the output from your competition, both nationally and internationally. The world has sped up.

In a state of accelerated innovation, we need AI tools just to keep our head above water. If your company can’t push out new and better products, they’ll be eclipsed by companies that can. If CEOs thin their number of employees, thinking it will yield more profits, that short-term thinking commits the fallacy of assuming that the goal posts are staying in the same position.

The release windows in which you must push out new software are shortening and becoming more frequent. Expectations about quality are increasing. You have to spend more time in research and development to ensure the competitor’s next release doesn’t put you out of business. This is why company layoffs might be a strategically poor decision: in an attempt to capture short-term profits, they shed the human validation resources needed to compete in the long-term, accelerated race.
(...)
We’re all accelerating and reeling from its effects. The idea of AI as liberation — liberation from all the tedious and time-consuming tasks you have to do — sounds much more appealing. But that liberation is a false narrative. AI isn’t liberating us. It’s speeding up the race. And we’re out of breath."

https://idratherbewriting.com/blog/ai-narrative-from-liberation-to-acceleration

#AI #GenerativeAI #Automation #Productivity #TechnicalWriting #SoftwareDocumentation #SoftwareDevelopment

TIL that GitHub Flavored Markdown includes a keyword+syntax combo that results in visually styled callouts (they call them "Alerts") when rendered on github:

start a section of quoted text with [!<keyword>]

Love it. Also, extensions like this really show why Markdown really isn't the best tool for the job. It needs SO many extensions to handle basic documentation stuff that's existed for a hundred years.

docs here: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

#TechnicalWriting

A Hacker News post on Deepnote, who have announced that they are going to be an open source replacement for Jupyyer Notebooks, drew my attention to another alternative that is highly recommended in some comments - Marimo.

Note to self: I should test this out sometime.
#TechnicalWriting #write_the_docs

https://marimo.io/blog/python-not-json

"We all learn through the generosity of others, and I think it's important that we find ways to support and enlarge the realm of generosity."

This observation by digital historian, @wragge is so true for all of us, no matter what profession, trade or industry we work or volunteer in.

Tim's work and generosity were instrumental in me gaining the skills I needed to work as a digital historian and more recently as a technical writer. I owe him a lot. He has helped so many people.

Read more of his brief reflections on his career:
#TechnicalWriting #write_the_docs #DigitalHumanities

https://updates.timsherratt.org/2025/11/03/me-at.html

"The basic idea of doc bug zero, as I explained in Defining bug zero, is to clear out all the tickets in the doc issue queue, essentially to finish all your documentation work. Doing so would be the ultimate statement about the productivity gains from AI. Despite my attempts to get to bug zero, it still eludes me. I’m realizing that there’s an art to working through a bug queue, and AI can only take me so far. Good project skills are also needed. One of those skills, which I’ll address in this post, is making it easy for people to review the changelists, or pull requests. (The terminology used in my area of doc work is changelists, or CLs, so that’s how I’ll refer to them here.)"

https://idratherbewriting.com/blog/make-easy-to-review-changelists

#TechnicalWriting #SoftwareDocumentation #ZeroBugs #Changelists #PullRequests