#softwaredocumentation — Public Fediverse posts

"Consider this idea: A company has 100 tech-writer-specific skills that are highly adopted and used across the organization. This collection of skills, focusing on internal authoring skills, has skills for doing virtually anything related to tech writing that you can imagine — fixing a bug, applying a style edit, checking release notes for accuracy, fixing comments in proto styles, and more. The skills don’t do the job entirely themselves but rather act as power tools for the writers, accelerating and amplifying their work.

Not everyone uses all 100 of the tech writer skills. Instead, each tech writer registers the skills most relevant to their tasks in their agent’s configuration. Some have even created virtual agents that have these skills.

Is this 100 TW skills idea worthwhile? The merits of the 100 skills idea are questionable; there are many problems associated with it — skills are hard to share because tech writing processes are idiosyncratic, monolithic skills that try to do too much get rejected, and there’s a fundamental trust problem when running someone else’s skill on your content. And yet, I think the idea could be interesting. We would essentially be externalizing the skills of an entire profession in a way that could be used cross-organizationally, by any role. This is unsettling as it may lead to our irrelevance. But there’s also a high possibility of amplification: by externalizing our skills, we build upon each others’ strengths. Is it possible to construct skills in such a way that other writers, particularly those who didn’t make the skills, find them useful?

In this series, I’ll build out these ideas into a course on skills."

https://idratherbewriting.com/ai/skills.html

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

"In this podcast, co-host Fabrizio Ferri-Benedetti and I chat with Sarah Deaton, a technical writer at Anthropic who works on the Claude Code docs, about what documentation work looks like when much of it is automated. We discuss orchestrating docs through skills and agents rather than writing them, mining AI assistant conversations for doc gaps, running forensics on every false claim that reaches the docs, new metrics like time-to-correction and steers per PR, the fences that keep AI-generated docs honest, and how she closed more than a hundred pull requests in a single day."

https://idratherbewriting.com/blog/podcast-deaton-anthropic-tw-automation

#TechnicalWriting #SoftwareDocumentation #Automation #DocsOrchestration #Anthropic #ClaudeCode #AIAgents #AgenticAI

I somewhat agree, but I'm still a sucker for non-fiction books. If a book is really good, it can provide you not just the required context and some knowledge of a given field, but also leave you with a few words of wisdom that can inspire you.

Also, I recommend everyone to follow what's cooking in /r/singularity

"Books and courses are traditional ways of learning. For senior tech writers, traditional learning won’t do. We’re living in the middle of a small technological revolution: new AI models, tools, and theories surface every week. Buying a book about anything that isn’t timeless theory or an established classic is now like buying an old newspaper: useful mainly as a historical record. Instead, stay abreast of tech news, because that’s the only thing that provides a return.

Staying up-to-date is not limited to reading Hacker News or Simon Willison’s blog: there’s also a very important social aspect to it. Join meetups in your area and enter Slack or Discord communities to replace the watercooler convos you had at work. Absorb trends, podcasts, worries, and jargon. It’s like moving to a new country: exhausting, but also exciting. In my case, I follow threads in several Slack communities where I can get a first-hand feeling of what’s cooking.

There are exceptions, of course. Books like the one CT Smith is writing, which focuses on how to sell technical writing to startup founders, are the right kind of material for this age. I, too, think that software is becoming marketing: as software becomes abundant, coding skills matter less than reputation and positioning. Docs are a service, not a deliverable: learn how to make the case for it. If you’re not a beginner, the only kind of books worth reading are the ones that teach you how to think and sell, not how to do the actual work. You already know the craft."

https://passo.uno/job-hunt-tech-writers-ai/

#TechnicalWriting #Documentation #AI #SoftwareDocumentation #ContentEngineering #SoftwareDevelopment

The truth is that LLMs are mostly unpredictable and, as such, you can’t rely on AI agents to strictly follow the instructions stored in a markdown file. Even when they execute all the instructions contained in the skills, they often leave a backtrail full of trash/dirt. Because they’re often unruly, they need another chatbot to put them in line, as well as a human in the loop, of course. Basically, it’s a lot of trial and error…

“I acknowledge that “programming an LLM” is putting it optimistically, as skills aren’t usually deterministic scripts. But I like to think of them this way, and keep refining the skill until it yields the consistent result that I want.
Overall, I’m persuaded that tech writers who can build successful skills to automate their tasks will be on their way to the 10x tech writer goal (if that’s your aim). The best way tech writers can free up their time is by creating skills to attack those repeatable tasks (like release notes) since repeatable tasks keep chipping away at our productivity week after week. If you can fashion a skill that handles those recurring tasks, then you free up a recurring amount of bandwidth each week.

Additionally, most repeatable tasks fall into the category of mechanical toil that we want to automate with AI anyway. If we can automate the repeatable tasks, then we’ll have more time to tackle the one-off complex tasks that don’t fall into our laps weekly or biweekly.”

https://idratherbewriting.com/blog/all-about-skills-intro

#AI #LLMs #AIAgents #AgenticAI #Skills #TechnicalWriting #SoftwareDocumentation

Here’s why contextual and use case-based documentation matters a lot when it comes to APIs:

“The problem is that documentation is often organized entirely around individual endpoints with very little cross-endpoint guidance, implicit prerequisites, or multi-step call documentation. For this reason, API use often involves tribal knowledge held by the average human operator.

A better way to organize this, or perhaps a complementary way, is to create documentation around workflows and common scenarios. You don't have to document every single potential interaction. In many cases, simply documenting common use cases and then delineating what they share is more than enough for the agentic systems to infer how the API actually functions in practice. This, alongside additional deterministic context, will help agents understand your systems in a human-like context without having to have a human on the other side of the request.

The goal: Provide documentation not just of individual endpoints but of the collective flow between them, allowing agents to understand your service properly.”

https://nordicapis.com/10-factors-for-checking-your-apis-ai-readiness/

#API #APIs #APIDocumentation #AI #AIAgents #TechnicalWriting #SoftwareDocumentation #APIDesign

"Now let me touch on an undiscussed aspect of skills I find interesting: skills enforce process. When I run my release documentation skill, I perform the same sequence of steps. As such, skills enforce a consistent process.

Some of the steps incorporate healthy habits into docs. For example, in my robust release docs skills, the following steps are followed:

- Analysis of source code comment tags (and any fixes)
- Analysis of logs run after the reference docs build to identify elements missing documentation.
- Analysis as to whether any changes/updates constitute breaking changes
Analysis of documentation corpus to identify needed changes across docs (and any fixes)

If I were doing these steps on my own, I might cut corners with some releases. For example, I probably wouldn’t have time to analyze the log reports or to scan all other documentation for needed updates. The skill helps me do these steps seamlessly.

Additionally, if you define a specific template for publishing, that template gets applied each time you run the skill, which also leads to more consistency."

https://idratherbewriting.com/blog/all-about-skills-intro

#AI #GenerativeAI #LLMs #Chatbots #Skills #Claude #Gemini #TechnicalWriting #SoftwareDocumentation

As a former tech journalist, I wholeheartedly agree with this!!

"A tech writer is that person who, like a seasoned reporter, chases the product news and presents it, making sure that they’ve collected the strongest evidence. It’s a matter of persistence. Like a particularly learned bulldog, the human writer won’t let go of the news: it’s theirs to bring past the finish line, which means going live, even if the outcome is rough around the edges. DevRels, once shunned by tech writers, are being vindicated in that their humanity is the only thing that can stand out in seas of slop.

For years, we have complained about being treated like formatting factories or syntax janitors. Now that AI is taking those tasks off our plates, and with them a certain comfort zone, we seem afraid to admit that our work is about chasing truth and providing fellow humans with direction. We are in the business of empowering people to build incredible stuff through AI, not that of sticking sentences together in files and chunking content using some dialect of XML. We can no longer hide behind chores: it’s time to guide."

https://passo.uno/tech-writing-role-split/

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

"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...

"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

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

That seems a bit similar to what I currently do... ;-)

"To use an analogy about my process, compare the scenario to a senior tech writer (TW) working next to a junior TW, where the senior TW mostly provides observation and feedback (in this analogy, the junior TW represents the AI agent). The junior TW creates some docs and presents them to the senior TW, who leaves comments explaining what needs to change. The junior TW takes notes about all the feedback in a journal. By the end of the process, the junior TW has three pages of notes.

After the process finishes, those notes aren’t lost. They form the basis of the SKILL file. The next time the senior TW sits down with another junior TW (a different one, as the session changed), the new junior TW produces much better output thanks to the notes. With each iteration, the notes get more detailed — anticipating common errors, adding validation checks, laying a foundation so that each step doesn’t build from faulty information. After a dozen iterations, the senior TW finds they have less and less feedback to give.

Eventually, the senior TW no longer needs to sit next to the junior TW in close observation. The junior TW proceeds autonomously through each step in the SKILL and just shows the final result. One key difference from real mentorship, though: the AI agent doesn’t carry any memory between sessions. It reads the SKILL file cold each time. All the “learning” lives in the document, not in the agent. This makes the SKILL file itself the critical asset — if it’s vague or incomplete, the agent’s output regresses immediately."

https://idratherbewriting.com/blog/internal-skills-release-docs

#TechnicalWriting #APIs #APIDocumentation #Skills #AgenticAI #AI #GenerativeAI #LLMs #SoftwareDocumentation

"Docs are beautiful when conceptual docs let the reader see the architecture, or when a tutorial lets them see their own hands on the keyboard. Diagrams and screenshots help, but they often compensate for prose that failed to produce an image on its own. Docs are visible when the reader can close their eyes and still see what the page described."

https://passo.uno/what-makes-docs-beautiful/

#Documentation #DocsAsProduct #SoftwareDocumentation #TechnicalWriting #SoftwareDevelopment

The great thing that Claude Code - or OpenAI Codex - brings to technical writers is that they can assess the accuracy of any piece of documentation that relies on software code, by analyzing the relevant code base(s).

This is extremely helpful because it definitely helps you fact-check your docs against the source code, namely to see if the Subject Matter Experts (SMEs) were bullshitting you or if the docs became outdated due to the cadence of new releases.

Another advantage is that even if you work in an organization with its own QA team, you can help them catch bugs at an earlier stage of the Software Development Life Cycle (SDLC). For example, yesterday I found an inconsistency between how a certain behavior was coded in the backend and how that same behavior was interpreted by the frontend.

And the best thing is that, since Claude Code does not entirely relies on neural networks but rather also uses regular expressions, the results have an higher degree of determinancy than the ones offered by common LLMs. Even though it's not perfect and you always have to tell it where to direct its attention (meaning the name of the most relevant repository) , this ability of taking advantage of a "Ai-based sniffer" for code is terrific.

For all these reasons I believe that every technical writer that doesn't use Claude Code or a similar toll in its own regular workflows will be immensely disadvantaged.

#TechnicalWriting #AI #GenerativeAI #SoftwareDocumentation #Claude #LLMs #GenerativeAI #ClaudeCode #SoftwareDevelopment #QA

This article is great in the sense that it describes most of what I'm doing nowadays as a technical writer. I even put different LLMs reviewing each other's drafts, which is a lot of fun. That's why, personally, I can't be so pessimistic as others are currently being. LLMs are just a new technology that you need to incorporate in your workflows. Of course, there are some skills that will probably become atrofied. At the same time, a new set of skills is emerging. If you don't see that. you will be completely left behind. You just need to use these tools by making use of critical thinking.

"After deliberation for a few months, I reached a conclusion about what I wanted to say: the model that’s emerging is a cyborg model of technical writing, a humans + AI combination. This is in contrast to the many articles, which now seem to come at an even faster pace, saying that AI will replace human labor. I realize there’s a lot of opinion on this debate, but my argument for why the humans + AI (cyborgs) model is the winning one, rather than replacement, is because of this observation: almost no tech writers at my work have automated complex processes using AI. And in my own use of AI over the past few years, the model that’s emerged is a close intertwining of machine and human interaction to produce content. I’m talking with AI all day. It’s not doing much on its own without my constant steering, direction, and feedback."

https://idratherbewriting.com/blog/cyborg-model-emerging-talk

#AI #GenerativeAI #LLMs #Chatbots #TechnicalWriting #TechnicalDocumentation #SoftwareDevelopment #SoftwareDocumentation

"With AI, the writer’s role moves to what I call context ownership. This is not a soft concept. A context owner is the person in your organization who governs what your AI tools know, how your content is structured, whether the output meets your quality and accuracy standards, and how your documentation systems connect to your product and engineering workflows.

In practice, context ownership looks like this:

A context owner defines and maintains the templates, standards, and structural rules that AI tools follow. Without these, AI produces content that is internally consistent within a single document but inconsistent across your documentation as a whole. Your customers notice, even if you don’t.

A context owner reviews and validates AI-generated drafts against product reality. AI tools do not know what your product actually does in edge cases. They do not know what changed in the last release that hasn’t been documented yet. They do not know that the API endpoint described in the engineering spec was modified during implementation. The context owner does.

A context owner manages the documentation pipeline. In a modern documentation operation, this means version control, docs-as-code workflows, API-driven publishing, and automated quality checks. These are technical systems that require technical management. AI can operate within these systems, but it cannot design, maintain, or troubleshoot them.

A context owner bridges engineering and customer-facing content. This is the function that has never been automated in any transition, and AI has not changed that. Someone has to understand what engineering built, determine what customers need to know about it, and make sure the documentation connects those two realities accurately.
(...)
This is not a diminished version of the writer’s role. It is a more senior, more technical role than “writer” has traditionally implied"
https://greenmtndocs.com/2026-03-25-ive-seen-this-before/
#AI #LLMs #TechnicalWriting #SoftwareDocumentation #ContextEngineering

"To begin with, everything you document has to be in a format that's as structured and machine-readable as possible. The key here is to disambiguate as much as you can, even if you have to repeat yourself. So, don't bother with the formatting of your documentation or the look and feel of your API portal. Instead, focus on using well-known API definition standards based on machine-readable formats. Use OpenAPI for documenting REST APIs, AsyncAPI for asynchronous APIs, Protocol Buffers for gRPC, and the GraphQL Schema Definition Language. Whenever possible, store the API definitions in several formats, such as JSON and YAML, for easy interpretation by AI agents.

But that's not enough. If you don't have all your operations clearly defined, AI agents will have a hard time understanding what they can do. Make sure you clearly define all operation parameters. Specify what the input types are so there are no misunderstandings. So, instead of saying that everything is a "string," identify each individual input format."

https://apichangelog.substack.com/p/api-documentation-for-machines

#APIs #APIDocumentation #AI #AIAgents #LLMs #OpenAPI #TechnicalWriting #SoftwareDocumentation #Programming

The problem is that most companies with the resources to properly implement role fluidity only want to hire "unicorns." Having worked in hybrid roles at smaller companies before and after the widespread adoption of LLMs, I must say that it's a recipe for burnout. This is not only because it's difficult to assess the quality of your work, but also because, in practice, companies don't care much about documentation. In reality, you'd mostly be a software developer doing some documentation in your "free time."

Another problem with this model of a fluid software documentation team is that it assumes there are or will be software companies willing to prioritize documentation as a sector that deserves its own department. However, technical writers are often placed under the product umbrella, which isn't necessarily bad. In fact, it's much better than being placed under "marketing." Unfortunately, if role fluidity ever becomes the norm, I'm afraid it will most likely start with engineering.

https://passo.uno/docs-team-of-the-future/

#TechnicalWriting #SoftwareDocumentation #Programming #SoftwareDevelopment #AI #LLMs

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

"Start small:

Pick one repeatable task that an agent currently handles without explicit guidance. Document it as a skill with entry criteria, steps, and exit criteria.

Validate it. Install skill-validator and run skill-validator check against your skill. Fix what it finds.

Test it with the agent. Invoke the skill explicitly and observe whether the agent follows it as written. Where it deviates, the skill is probably ambiguous.

Add validation to CI. Once you have a few skills, the CI integration keeps them from degrading as the project evolves.

Perhaps unsurprisingly, this is the same pattern I described for project descriptions: start with one file, observe how agents respond, iterate. The difference is that skills demand more precision because they're more prescriptive. That higher quality bar makes deterministic validation tooling valuable; you get feedback on skill quality before the agent runs, not after."

https://instructionmanuel.com/writing-skills-agents-can-execute

#AI #AIAgents #GenerativeAI #Skills #LLMs #TechnicalWriting #Documentation #SoftwareDocumentation

"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

"I ask AI to explain things all the time. If I observe it do something that I want to learn more about, I ask it. I look at its outputs and ask it to explain decisions it made or how it implemented something. I ask it to help me brainstorm about things, help me think through edge cases or performance considerations, you name it. If the thing that it is explaining has some implication I need to verify, I ask it to find me a link that backs up what it is saying. And then I look at the link to make sure the content is real, comes from a reasonable source, and actually backs up what the AI says. And probaly also ask it questions about the surface area around the thing, until I’m sure I understand it.

If you approach the AI upskill process as a collaborative learning process, where you can interrogate the tool you’re learning about its capabilities, how and why it’s chosing to do the things it’s doing, and to explain anything you don’t understand along the way - you’re unlocking a super power.

AND you have the comfort of knowing you’re asking all your questions of a talking box that won’t remember what you asked the next time it chats with you. So even if you do think it’s judging you, it has amnesia and that judgement won’t last beyond closing the session!"

https://dacharycarey.com/2026/02/23/upskilling-in-ai-age/

#TechnicalWriting #AI #LLMs #AIAgents #Chatbots #SoftwareDocumentation

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

"Test your documentation site against the Agent-Friendly Documentation Spec.

Agents don't use docs like humans. They hit truncation limits, get walls of CSS instead of content, can't follow cross-host redirects, and don't know about quality-of-life improvements like llms.txt or .md docs pages that would make life swell. Maybe this is because the industry has lacked guidance - until now.

afdocs runs 21 checks across 8 categories to evaluate how well your docs serve agent consumers. 10 are fully implemented; the rest return skip until completed."

https://www.npmjs.com/package/afdocs

#TechnicalWriting #SoftwareDocumentation #AI #AIAgents #Afdocs #Markdown #DocsAsCode #LLMSTXT