"An engineer named Siddhant Khare wrote recently about what he called “AI fatigue” — the exhaustion that comes not from creating but from reviewing. Before AI, his day had a rhythm: think about a problem, write code, test it, ship it. After AI, his day became a loop of prompting, waiting, reading output, evaluating output, deciding if the output was correct, deciding if it was safe, fixing the parts that weren’t, and re-prompting. He described it as becoming a quality inspector on a conveyor belt that never stops. The work was faster but emptier. The flow states that used to sustain him — the deep, energizing focus of building something yourself — had been replaced by the shallow, draining focus of judging something you didn’t build.

Not every writer experiences this the same way. For some, the shift is actually liberating. If your day job involves writing yet another SDK migration guide or documenting the fine-grained differences between configuration parameters across product tiers — content you won’t remember in a month — there’s no loss of creative joy when the machine drafts it for you. You become the editor, not the author, and you save your real creative energy for work that matters to you personally. The fatigue isn’t from reviewing; it’s from pretending that all documentation deserves the same emotional investment. Some of it is toil, and outsourcing toil is fine.

But here’s the tension: if you stop caring about the work the machine produces, who maintains the quality? This is where the concept of ownership becomes critical. The tech writers who thrive in this landscape aren’t the ones who wait for engineers to hand them drafts to edit. They’re the ones who own the reference documentation, who run diffs against every API release, who update architectural diagrams, who maintain a single source of truth..."

https://idratherbewriting.com/blog/judging-beautiful-docs-ai-fatigue-podcast

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

Software Engineering’s Reliance on Informal Knowledge and Its Limits in the Age of AI

📰 Original title: The Oral Tradition That Built Software May Not Survive AI

🤖 IA: It's not clickbait ✅
👥 Users: It's not clickbait ✅

View full AI summary https://en.killbait.com/software-engineering-s-reliance-on-informal-knowledge-and-its-limits-in-the-age-of-ai.html?utm_source=mastodon_world&utm_medium=social&utm_campaign=killbait.mastodon_world

#technology #softwaredocumentation #institutionalknowl...

Software Engineering’s Reliance on Informal Knowledge and Its Limits in the Age of AI

📰 Original title: The Oral Tradition That Built Software May Not Survive AI

🤖 IA: It's not clickbait ✅
👥 Users: It's not clickbait ✅

View full AI summary https://en.killbait.com/software-engineering-s-reliance-on-informal-knowledge-and-its-limits-in-the-age-of-ai.html?utm_source=mastodon_social&utm_medium=social&utm_campaign=killbait.mastodon_social

#technology #softwaredocumentation #institutionalkno...

"Using MCP, agents can fetch structured data contextually relevant to the task at hand. According to Edgar Kussberg, group product manager at Sonar, MCP accelerates the knowledge-hunting engineers must routinely perform on a daily basis.

“When an engineer needs to answer a question, they do not rely on memory alone,” says Kussberg. “They navigate code repositories, dashboards, CI systems, documentation, and security reports, pulling information from each system as needed. MCP gives AI agents that same capability.”

Many of the most popular MCP servers retrieve contextual information to improve agentic coding. For example, an MCP server from Context7 provides up-to-date documentation, while another from Filesystem pulls from any directory on a local machine. An MCP server from Sentry accesses production issues and errors, a server from SonarQube exposes security issues, and a server from Multiplayer returns user session data.

The great thing about using MCP for these situations is that it avoids the need to put large code chunks in every prompt. Instead, coding context like relevant methods, dependencies, or recent changes can be called at runtime, says Venugopal Jidigam, head of agentic platform engineering at WaveMaker, an agentic development platform. “The MCP server assembles and returns scoped, structured context, which the model then uses to reason and respond accurately,” he says.

Another common context-gathering example is retrieving institutional knowledge. “Instead of hardcoding that knowledge into the model, the agent uses MCP to retrieve relevant documents or data at runtime,” says Ebrahim Alareqi, principal machine learning engineer at Incorta, a data and analytics platform provider. “This keeps the agent lightweight while still giving it access to enterprise-specific context when needed.”"

https://www.infoworld.com/article/4175336/the-role-of-mcp-in-context-engineering.html

#AI #GenerativeAI #LLMs #MCP #ContextEngineering #Documentation #SoftwareDocumentation #AIAgents #AgenticAI

"If you are thinking about using an AI agent for documentation, here is what I think matters most.

Teach the agent, do not just instruct it. A prompt that says "write documentation for this feature" produces generic content. A skill that defines your voice, your formatting rules, your page structure, and your verification checklist produces documentation that sounds like your team wrote it. The upfront investment in the skill pays off on every subsequent page.

Make screenshots reproducible. Manual screenshots are the first thing that goes stale. A declarative manifest that can regenerate every screenshot in one command is worth the engineering effort. It changes screenshots from a one-time cost to a maintained artifact.

Phase your work. Even if you are using an agent, "write all the docs" is not a plan. Break it into phases with clear scope and clear deliverables. This gives you stopping points, review points, and the ability to course-correct.

Expect things to break. OCR will misread text. The UI will change mid-sprint. Preview URLs will go stale. The difference between a frustrating experience and a productive one is whether you encode the fix into a skill so it never happens again.

Review everything. The agent does not replace your judgment. It replaces the mechanical work. You still need to read every page, check every screenshot, and verify that the documentation matches what the user actually sees. The agent writes the first draft. You make it right."

https://dev.to/debs_obrien/how-i-documented-an-entire-product-in-4-days-with-an-ai-agent-3338

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

"The future of enterprise technical documentation will not belong to organizations that merely generate more content with AI. It will belong to organizations that build semantically governed, operationally validated, and explainable knowledge ecosystems around AI generation.

Large language models are remarkable language-generation systems, but they remain fundamentally probabilistic, and no amount of vector-based probabilistic augmentation, recursive prompt gymnastics, or trillions of additional parameters magically transforms probabilistic token prediction into deterministic operational intelligence — regardless of what the AI snake-oil salesmen on LinkedIn insist between inspirational rocket-ship emojis. LLMs predict statistically likely outputs. They do not inherently understand operational correctness, governance policy, procedural safety, rollback integrity, regulatory compliance, or whether the “helpful” configuration change they just suggested is going to quietly detonate a production Kubernetes cluster at 2:13 a.m. while everyone is asleep and the on-call engineer is reconsidering their career choices.

That is not a moral failure of AI. It is simply the architectural reality of probabilistic systems pretending to perform deterministic operational reasoning often enough to make people dangerously optimistic.

This is precisely why deterministic models and governance matter.

Structured content, semantic markup, metadata governance, provenance tracking, DOM Graph RAG, iiRDS frameworks, knowledge graphs, RDF and OWL ontologies, context graphs, deterministic inference engines, orchestration platforms, Docs-as-Tests automation, and runtime observability together create something fundamentally different from prompt engineering. They create governed operational ecosystems capable of supporting trustworthy enterprise AI at scale."

https://medium.com/@nc_mike/deterministic-and-agentic-ai-architectures-for-technical-documentation-3fb2956a1334

#AI #GenerativeAI #DocsAsTests #LLMs #AgenticAI #DITAXML #AIAgents #TechnicalWriting #SoftwareDocumentation

The cost of not documenting software AKA why software companies will continue to need to hire and keep technical writers:

"Perhaps bizarrely, "the best documented game" in CD Projekt's history according to Ruciński is spin-off Witcher cardgame Gwent. "In a live service environment, which you could argue Gwent was, it is easy to say that you don't have the time to document everything, because the game is changing so fast," he said. "It receives patches, new content, new balance, every month. So all those documents need to be constantly updated, and somebody has to do that. It is a cost."

The developers opted to "pay this documentation tax upfront", however, rather than kick it down the road. As a result, said Ruciński, "new artists, new coders, new designers could jump onto any task within Gwent and contribute instantly." This demonstrates that "documentation doesn't have to slow you down, you don't have to think of documentation as something that will only be useful years later. Documentation can actually speed you up, make you faster right now."

Things didn't go nearly so well during the creation of Cyberpunk 2077 – a "true test of scale" for CD Projekt's technical writers. "Cyberpunk was a fresh start, but it came with new problems," Fulneczek recalled. "It was a massive undertaking. The hopes and expectations surrounding it were enormous. Internally, we had our documentation tool, Confluence, we had a proof of concept of 'living' documentation, so we thought, we were ready.

"But it turned out we weren't, because Cyberpunk was the first project of this scale, this size that we documented, and it also took a very long time," he went on. "And during those eight, nine years of development, we created over 8000 pages of documentation, and that's because of how complex this project was, and it also had many iterations along the way..."

https://www.rockpapershotgun.com/it-was-chaos-how-the-witcher-4-and-cyberpunk-2-are-learning-from-decades-of-cd-projekts-documentation-mistakes

#TechnicalWriting #SoftwareDocumentation #Documentation #Videogames #TechnicalCommunication

"Back in 2024 I wrote that AI helps me remove boring work at the margins. This is fine for a lone writer, but how to scale this to an entire team of technical writers? How to make the system helpful but not intrusive? These are all questions I’m starting to answer now, partly through experimentation, but also through dialogue with practitioners and colleagues. One answer I’m testing these days relies on GitHub Agentic Workflows.

Following Four modes of AI-augmented technical writing, I thought of a way of distributing tooling effort across all modes through a tiered system where each level holds a different relationship with the writer. The result is four tiers: intake, local assistance, automated governance, and an MCP server that provides reliable knowledge to all. The idea is that AI assists the writer not just while writing, but also before and after they work on docs."

https://passo.uno/agentic-workflows-for-docs/

#TechnicalWriting #AI #GenerativeAI #LLMs #AIAgents #AgenticAI #AgenticWorkflows #SoftwareDocumentation #GitHub #DocsAsCode

Interesting article on API documentation best practices.

The author focuses on web APIs, but I think this article applies to classic APIs (those in our packages or that we generate ourselves for other teams).

In short, it's always advisable to provide two types of documentation: the specifications (the "what") and the API documentation (the "how").

https://inkwright.inc/blog/your-api-reference-is-not-your-api-documentation

#SoftwareDocumentation #api

I don't agree at all with the statement that "API documentation is not technical writing" and also with the notion a technical writer can't necessary know enough about programming without being a software developer - hint: how many Udemy courses are there about API development, API design and AP programming? Hundreds? Thousands?

Also, nowadays, with tools like Claude Code and Codex, testing APIs through platforms like Postman should be seen as stuff for QA analysts and not exactly for technical writers, since AI tools such as those allow you to have a more contextualized look at what a specific API endpoint does, specifically in terms of edge cases and "odd balls". As a technical writer, I can ask these tools to highlight specific use cases where the endpoint can be really useful.

That's not to say that the process can be completely automated. Not at all. Specially because an how-to guide explaining how to make use of an API endpoint couldn't essentially be completely triggered by an LLM. Besides, for the foreseeable future and probably even beyond that, the final output should always be reviewed by an engineer. In any case, what I'm talking about is totally different from automatically generally API reference documentation.

But there is no point in knowing how to send a request to an API endpoint and the typical response will be - both in case of success and error -, if I, as a developer, don't have a compelling enough reason to use that endpoint. Another totally different thing is an API Integration tutorial, that is, how to integrate a complete API into your own app. But here you will, of course, also need the intervention of a, guess what, TECHNICAL WRITER!! :-D

"I have said that API documentation is not technical writing and that it is a mistake to try. There are many details clients need to have. This includes format, presentation, and client experience."

https://robertdelwood.medium.com/more-about-api-documentation-errors-part-i-969999176c9f

#TechnicalWriting #API #APIs #APIDocumentation #SoftwareDocumentation