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

"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

"Consumers want to be able to try an API operation and access concrete example information, or configuration data, such as credentials. Markdown alone isn’t going to provide these elements for you. Fortunately, there’s something else that will, as we’ll see next.

The solution you need is called MDX. It’s a superset of Markdown that lets you embed components within your content. Or just render dynamic information obtained from executing JavaScript. You get to keep the simplicity and versatility of Markdown. But now, you can also use dynamic elements and data. This completely changes the game for API documentation. You can, for instance, embed a component to show the consumer’s API key, or one to make an API request and show its response. This hands-on interactivity helps users test the API faster. And, because of that, it significantly reduces the Time to First Call, or TTFC. Since a low TTFC means the API onboarding experience is excellent, it translates directly into a higher perception of quality. Which is exactly what you’re looking for.

Moving from pure Markdown to MDX doesn’t have to be complicated. However, and especially if you have little coding experience, putting an MDX system together from scratch can be challenging. Luckily, there are many systems that already support MDX. Docusaurus, for instance, supports it by default. Astro is another example of a content system where you can use MDX. There are more options, including commercial ones. What I’d recommend, though, is to check out the official documentation and have a go at the MDX playground."

https://apichangelog.substack.com/p/making-api-documentation-dynamic

#API #APIDocumentation #TechnicalWriting #Markdown #MDX #APIDesign #DX #DeveloperExperience

"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

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

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

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

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

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

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

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

"The reality is that documentation is no longer just a piece of context or data found when an external developer runs into an issue — it’s a first-class context object that needs to be treated with the same focus and intentionality as the API itself. Within this context, MCP offers something more than just putting all the documentation in a single store and hoping for the best — it provides a direct pathway between the developer and the provider, allowing you to discover intent, and clarity like no other process currently on offer.

As we move towards a future focused around API discovery, we need to rethink how we look at documentation and its discovery — and solutions like MCP are going to play a huge part in making documentation and data clearer, more contextual, and more available."

https://nordicapis.com/using-mcp-for-api-documentation-discovery/

#AI #GenerativeAI #AIAgents #AgenticAI #MCP #MCPServers #Documentation #APIDocumentation #SoftwareDocumentation #DeveloperDocumentation #APIs #APIDiscovery

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

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

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

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

Skills & traits for developing trustworthy information

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

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

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

"In this scenario, it doesn't make a lot of sense to target your API documentation exclusively at developers. It's definitely time to write it in a way that your non-technical stakeholders understand. So, how can you document your API capabilities?

Identifying capabilities is an exercise that begins with understanding the benefits your API offers to consumers. Benefits are the things that consumers obtain after they use your API, not what your API has to offer. You need to understand how consumers use your API and what their daily habits are. A good framework is studying your consumers' jobs-to-be-done (JTBD). Each JTBD represents something one or more consumers are trying to accomplish by using your API. After you group JTBDs by categories according to their similarity, you'll notice that clusters of benefits begin to emerge. If you then order those clusters by degree of criticality, you end up with a list of the most important benefits your API offers to potential consumers. I think you can already see where this is leading. With the list of benefits, you can get to a list of API capabilities by translating each one. While the benefit is what consumers achieve, the capability is what helps them get there. Let's look at an example to make things easier."

https://apichangelog.substack.com/p/documenting-your-api-around-its-capabilities

#API #APIs #APIDocumentation #TransactionEnrichment #TechnicalWriting #SoftwareDocumentation #SoftwareDevelopment