#apidocumentation — Public Fediverse posts

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

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

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

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

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

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

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

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

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

Ah, the latest in API documentation, because nothing screams "user-friendly" like a 157-step guide to "Your First API Call" 🤦‍♂️. #DeepSeek v4 promises compatibility with #OpenAIAnthropic (whatever that means), but it's basically just a choose-your-own-adventure for APIs, minus the adventure. 🚀✨
https://api-docs.deepseek.com/ #APIDocumentation #UserFriendly #TechHumor #HackerNews #ngated

Learn how to structure API documentation developers can actually use, with practical examples covering quickstart, auth, references, and more. https://hackernoon.com/how-to-structure-api-documentation #apidocumentation

"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

"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

"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

"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

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

"As AI tools became more capable, I realized that generating these diagrams wasn’t so hard. AI tools are actually great at creating them, which reduces the effort around both authoring and maintenance. I now have quick reference diagrams for every one of the APIs I support. These QRGs don’t just provide documentation usability; they augment AI chat sessions in helpful ways, especially when you’re constrained by how many tokens you can add into your AI session context.

In this article, I’ll walk through the process of using AI to create a quick reference diagram. I’ll share my thought processes behind the approach, how AI tools are used, and other decision-making. I’ll also show how to provide instruction to an agent to build everything in a single instruction.

Overall, the QRG as a comprehensive tree diagram provides a number of benefits:

- Enhances API usability for developers. Developers love quick reference guides, and this gives them an easy way to Ctrl+F to find any element and go directly to it.

- Serves as a concise summary for AI. The QRG offers a compact representation of the API, useful for priming AI tools or navigating large documentation sets within token limits."

https://idratherbewriting.com/ai/prompt-eng-api-qrgs.html

#TechnicalWriting #APIs #API #APIDocumentation #AI #GenerativeAI #References #QRG

"As AI tools became more capable, I realized that generating these diagrams wasn’t so hard. AI tools are actually great at creating them, which reduces the effort around both authoring and maintenance. I now have quick reference diagrams for every one of the APIs I support. These QRGs don’t just provide documentation usability; they augment AI chat sessions in helpful ways, especially when you’re constrained by how many tokens you can add into your AI session context.

In this article, I’ll walk through the process of using AI to create a quick reference diagram. I’ll share my thought processes behind the approach, how AI tools are used, and other decision-making. I’ll also show how to provide instruction to an agent to build everything in a single instruction.

Overall, the QRG as a comprehensive tree diagram provides a number of benefits:

- Enhances API usability for developers. Developers love quick reference guides, and this gives them an easy way to Ctrl+F to find any element and go directly to it.

- Serves as a concise summary for AI. The QRG offers a compact representation of the API, useful for priming AI tools or navigating large documentation sets within token limits."

https://idratherbewriting.com/ai/prompt-eng-api-qrgs.html

#TechnicalWriting #APIs #API #APIDocumentation #AI #GenerativeAI #References #QRG

"As AI tools became more capable, I realized that generating these diagrams wasn’t so hard. AI tools are actually great at creating them, which reduces the effort around both authoring and maintenance. I now have quick reference diagrams for every one of the APIs I support. These QRGs don’t just provide documentation usability; they augment AI chat sessions in helpful ways, especially when you’re constrained by how many tokens you can add into your AI session context.

In this article, I’ll walk through the process of using AI to create a quick reference diagram. I’ll share my thought processes behind the approach, how AI tools are used, and other decision-making. I’ll also show how to provide instruction to an agent to build everything in a single instruction.

Overall, the QRG as a comprehensive tree diagram provides a number of benefits:

- Enhances API usability for developers. Developers love quick reference guides, and this gives them an easy way to Ctrl+F to find any element and go directly to it.

- Serves as a concise summary for AI. The QRG offers a compact representation of the API, useful for priming AI tools or navigating large documentation sets within token limits."

https://idratherbewriting.com/ai/prompt-eng-api-qrgs.html

#TechnicalWriting #APIs #API #APIDocumentation #AI #GenerativeAI #References #QRG

"As AI tools became more capable, I realized that generating these diagrams wasn’t so hard. AI tools are actually great at creating them, which reduces the effort around both authoring and maintenance. I now have quick reference diagrams for every one of the APIs I support. These QRGs don’t just provide documentation usability; they augment AI chat sessions in helpful ways, especially when you’re constrained by how many tokens you can add into your AI session context.

In this article, I’ll walk through the process of using AI to create a quick reference diagram. I’ll share my thought processes behind the approach, how AI tools are used, and other decision-making. I’ll also show how to provide instruction to an agent to build everything in a single instruction.

Overall, the QRG as a comprehensive tree diagram provides a number of benefits:

- Enhances API usability for developers. Developers love quick reference guides, and this gives them an easy way to Ctrl+F to find any element and go directly to it.

- Serves as a concise summary for AI. The QRG offers a compact representation of the API, useful for priming AI tools or navigating large documentation sets within token limits."

https://idratherbewriting.com/ai/prompt-eng-api-qrgs.html

#TechnicalWriting #APIs #API #APIDocumentation #AI #GenerativeAI #References #QRG

"As AI tools became more capable, I realized that generating these diagrams wasn’t so hard. AI tools are actually great at creating them, which reduces the effort around both authoring and maintenance. I now have quick reference diagrams for every one of the APIs I support. These QRGs don’t just provide documentation usability; they augment AI chat sessions in helpful ways, especially when you’re constrained by how many tokens you can add into your AI session context.

In this article, I’ll walk through the process of using AI to create a quick reference diagram. I’ll share my thought processes behind the approach, how AI tools are used, and other decision-making. I’ll also show how to provide instruction to an agent to build everything in a single instruction.

Overall, the QRG as a comprehensive tree diagram provides a number of benefits:

- Enhances API usability for developers. Developers love quick reference guides, and this gives them an easy way to Ctrl+F to find any element and go directly to it.

- Serves as a concise summary for AI. The QRG offers a compact representation of the API, useful for priming AI tools or navigating large documentation sets within token limits."

https://idratherbewriting.com/ai/prompt-eng-api-qrgs.html

#TechnicalWriting #APIs #API #APIDocumentation #AI #GenerativeAI #References #QRG

"This article examines several more common problems occurring in API documentation. They are easily prevented or have simple workarounds but the writer must be aware of them in the first place. These underscore the importance of:

- Writers being familiar with programming and development concepts, so that,
- Writers can think like developers. Only by thinking like a developer can writers then hone in on client’s nuances, customize the developer experience, and optimize the time in the documentation. The goal is an ironic one. We want documentation so good and clear that clients don’t even have to read it. You’ll see what I mean in a moment.

The striking thing about these is how simple they seem. So much so, they are often overlooked. Afterall, how much can be said about an offset value of a returned list, or sorting? As it turns out, plenty. Thinking like developer is encompassing. Enough information must be presented so that clients know ahead of time what the field or endpoint does, returns, what the behavior is, and what each parameter does. You have to anticipate questions and understand how clients think about things. The last thing we writers want for clients is to make them experiment with values and guess outcomes. That annoys them and wastes their time. It means we didn’t do our job.

API documentation is not technical writing. It’s API documentation writing. The key differences are the dependence on code and a deep understanding of development practices. There are countless nuances and subtleties — and each one matters to developers. How can it not? You’re writing to developers about development. It needs to be precise and it needs to speak their language."

https://robertdelwood.medium.com/more-common-api-documentation-errors-26f1a8ceaaec

#APIs #APIDocumentation #TechnicalWriting #Programming #SoftwareDevelopment #TechnicalCommunication

One Open-source Project Daily

Offline documentation browser inspired by Dash

https://github.com/zealdocs/zeal

#1ospd #opensource #api #apidocumentation #dash #desktopapplication #developertools #docs #docset #documentation #documentationtool #offline #qt #zeal

One Open-source Project Daily

Offline documentation browser inspired by Dash

https://github.com/zealdocs/zeal

#1ospd #opensource #api #apidocumentation #dash #desktopapplication #developertools #docs #docset #documentation #documentationtool #offline #qt #zeal

One Open-source Project Daily

Offline documentation browser inspired by Dash

https://github.com/zealdocs/zeal

#1ospd #opensource #api #apidocumentation #dash #desktopapplication #developertools #docs #docset #documentation #documentationtool #offline #qt #zeal

One Open-source Project Daily

Offline documentation browser inspired by Dash

https://github.com/zealdocs/zeal

#1ospd #opensource #api #apidocumentation #dash #desktopapplication #developertools #docs #docset #documentation #documentationtool #offline #qt #zeal

One Open-source Project Daily

Offline documentation browser inspired by Dash

https://github.com/zealdocs/zeal

#1ospd #opensource #api #apidocumentation #dash #desktopapplication #developertools #docs #docset #documentation #documentationtool #offline #qt #zeal

"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

"Finding the right API is rarely straightforward. But once the AI locates an API, it needs to be evaluated. This is where API documentation comes in. Detailed descriptions tell AI what the API does, what data formats it uses, what authentication systems are in place, and any limitations it might have.

Good API documentation allows developers to speak directly to machines as well as human users. To enhance this process, generative engine optimization (GEO) is becoming increasingly important. Clear, well-defined data, articulate endpoint descriptions, parameter explanations, code snippets, sample calls, and real-world use cases all aid GEO as they provide context for picking the right API and improving understandability. llms.txt, an emerging standard similar to robots.txt but for AI, is becoming more useful for discovery, as it tells an LLM exactly what to look for instead of assessing each site path and making its best guess.

Improving API discoverability helps guarantee that the LLM always gets the most up-to-date information and data. It’s also a vital component of retrieval-augmentation generation (RAG), which makes good API documentation doubly vital as it allows AI to discover internal APIs as well as public ones, and supply the generation layer with accurate, relevant details."

https://nordicapis.com/how-to-optimize-api-documentation-for-ai-discoverability/

#APIs #APIDocumentation #GEO #APIDiscoverability #RAG #LLMs #AI #GenerativeAI #Metadata #TechnicalWriting #SoftwareDocumentation

"Finding the right API is rarely straightforward. But once the AI locates an API, it needs to be evaluated. This is where API documentation comes in. Detailed descriptions tell AI what the API does, what data formats it uses, what authentication systems are in place, and any limitations it might have.

Good API documentation allows developers to speak directly to machines as well as human users. To enhance this process, generative engine optimization (GEO) is becoming increasingly important. Clear, well-defined data, articulate endpoint descriptions, parameter explanations, code snippets, sample calls, and real-world use cases all aid GEO as they provide context for picking the right API and improving understandability. llms.txt, an emerging standard similar to robots.txt but for AI, is becoming more useful for discovery, as it tells an LLM exactly what to look for instead of assessing each site path and making its best guess.

Improving API discoverability helps guarantee that the LLM always gets the most up-to-date information and data. It’s also a vital component of retrieval-augmentation generation (RAG), which makes good API documentation doubly vital as it allows AI to discover internal APIs as well as public ones, and supply the generation layer with accurate, relevant details."

https://nordicapis.com/how-to-optimize-api-documentation-for-ai-discoverability/

#APIs #APIDocumentation #GEO #APIDiscoverability #RAG #LLMs #AI #GenerativeAI #Metadata #TechnicalWriting #SoftwareDocumentation

"Finding the right API is rarely straightforward. But once the AI locates an API, it needs to be evaluated. This is where API documentation comes in. Detailed descriptions tell AI what the API does, what data formats it uses, what authentication systems are in place, and any limitations it might have.

Good API documentation allows developers to speak directly to machines as well as human users. To enhance this process, generative engine optimization (GEO) is becoming increasingly important. Clear, well-defined data, articulate endpoint descriptions, parameter explanations, code snippets, sample calls, and real-world use cases all aid GEO as they provide context for picking the right API and improving understandability. llms.txt, an emerging standard similar to robots.txt but for AI, is becoming more useful for discovery, as it tells an LLM exactly what to look for instead of assessing each site path and making its best guess.

Improving API discoverability helps guarantee that the LLM always gets the most up-to-date information and data. It’s also a vital component of retrieval-augmentation generation (RAG), which makes good API documentation doubly vital as it allows AI to discover internal APIs as well as public ones, and supply the generation layer with accurate, relevant details."

https://nordicapis.com/how-to-optimize-api-documentation-for-ai-discoverability/

#APIs #APIDocumentation #GEO #APIDiscoverability #RAG #LLMs #AI #GenerativeAI #Metadata #TechnicalWriting #SoftwareDocumentation

"Finding the right API is rarely straightforward. But once the AI locates an API, it needs to be evaluated. This is where API documentation comes in. Detailed descriptions tell AI what the API does, what data formats it uses, what authentication systems are in place, and any limitations it might have.

Good API documentation allows developers to speak directly to machines as well as human users. To enhance this process, generative engine optimization (GEO) is becoming increasingly important. Clear, well-defined data, articulate endpoint descriptions, parameter explanations, code snippets, sample calls, and real-world use cases all aid GEO as they provide context for picking the right API and improving understandability. llms.txt, an emerging standard similar to robots.txt but for AI, is becoming more useful for discovery, as it tells an LLM exactly what to look for instead of assessing each site path and making its best guess.

Improving API discoverability helps guarantee that the LLM always gets the most up-to-date information and data. It’s also a vital component of retrieval-augmentation generation (RAG), which makes good API documentation doubly vital as it allows AI to discover internal APIs as well as public ones, and supply the generation layer with accurate, relevant details."

https://nordicapis.com/how-to-optimize-api-documentation-for-ai-discoverability/

#APIs #APIDocumentation #GEO #APIDiscoverability #RAG #LLMs #AI #GenerativeAI #Metadata #TechnicalWriting #SoftwareDocumentation

"Finding the right API is rarely straightforward. But once the AI locates an API, it needs to be evaluated. This is where API documentation comes in. Detailed descriptions tell AI what the API does, what data formats it uses, what authentication systems are in place, and any limitations it might have.

Good API documentation allows developers to speak directly to machines as well as human users. To enhance this process, generative engine optimization (GEO) is becoming increasingly important. Clear, well-defined data, articulate endpoint descriptions, parameter explanations, code snippets, sample calls, and real-world use cases all aid GEO as they provide context for picking the right API and improving understandability. llms.txt, an emerging standard similar to robots.txt but for AI, is becoming more useful for discovery, as it tells an LLM exactly what to look for instead of assessing each site path and making its best guess.

Improving API discoverability helps guarantee that the LLM always gets the most up-to-date information and data. It’s also a vital component of retrieval-augmentation generation (RAG), which makes good API documentation doubly vital as it allows AI to discover internal APIs as well as public ones, and supply the generation layer with accurate, relevant details."

https://nordicapis.com/how-to-optimize-api-documentation-for-ai-discoverability/

#APIs #APIDocumentation #GEO #APIDiscoverability #RAG #LLMs #AI #GenerativeAI #Metadata #TechnicalWriting #SoftwareDocumentation

"[W]henever I need a Redocly or Swagger UI CLI command, again, I use ChatGPT. And it does something the site doesn’t do in that I get completed commands ready to run. Easier, faster, and more productive than going to your site. Writers may not do this a lot themselves. Developers do. This is where thinking like a developer comes in. They use AI for programming. Don’t take my word for it. Ask around. Watch developers work. Write an application yourself, something I advocate API documentation writers must do anyhow. These suggestions are for seeing how AI is creeping into the developer’s work style.

That means developer don’t know or care what the site looks like. Only that the content is there. The key is that AI doesn’t make up information. It gets it from somewhere. And that somewhere is your site. The more complete the information, field explanations (remember this one from earlier?), and interactions, the more complete the AI can be. That means happier developers.

In that regard, writers will always have a job writing content. Writers won’t always have a job formatting the output or publishing files. Your publishing tools are needed for the moment. But you need to be thinking two to five years in advance. Now."

https://robertdelwood.medium.com/writing-api-documentation-for-ai-and-not-developers-d245f8b97c18

#TechnicalWriting #APIs #APIDocumentation #SoftwareDevelopment #AI #GenerativeAI #Programming

"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

"A documentation platform is a product that provides capabilities—some free; some paid—for a range of activities, like authoring, editing, collaborating, monitoring, building, deploying, and publishing documentation.

Docs-as-code platforms are more common these days, as more people can code or leverage systems like AI that help them code. Traditionally, authoring to publication might take place locally, or via a software product that offered manual versioning, limited collaboration, and limited-to-no support for documentation pipeline automation, like setting up a CI/CD pipeline to deploy health documentation when the `main` has a new commit. If you remember the yesteryears of authoring, products like Subversion and TortoiseSVN may come to mind.

The platforms I’m writing about today are modern and all offer some type of free documentation generation, usually through static site generation; however, outside of what’s provided out of the box, there are notable differences between what’s provided for free and what’s provided at cost.

My goal for this article is to point out some core differences across add-ons, features, and enterprise-level support across these documentation platforms so that you choose the platform that’s best for you and your documentation readers.

For this article, I researched Fern, Mintlify, ReadMe, and Redocly."

https://www.copytree.io/post/choosing-modern-docs-platform

#TechnicalWriting #SoftwareDocumentation #APIDocumentation #APIs #SoftwareDevelopment #Programming #DocsAsCode

"In our piece exploring whether the AI revolution is leaving APIs behind, we wrote about some of the factors limiting the extent to which AI tools like chatbots can interface with APIs.

Some of these include:

- Limited or no access to APIs for developers
- APIs are sometimes overcomplicated, bloated, or difficult to call
- Legacy APIs (WS/RPC) lack thorough or up-to-date documentation
- APIs sometimes only cover a fraction of the functions available via the UI

It’s worth noting that many of these points impact human API consumers just as much as they do agentic ones. If you’ve ever been in the position of trying to use an API and it falling short of your expectations, you’ll know just how frustrating it can be.

While it’s possible that some of those users will get in touch to ask you to add certain endpoints or clarify things, plenty more won’t. Some developers are more likely to take the view that it’s easier to ask for forgiveness later than permission now, and find some other way to extract the data they’re looking for. In many cases, web scraping offers just such a solution.

Web scraping APIs are a natural evolution of manual scraping techniques, such as using Python to scrape websites. Used for everything from scraping search engine results, like SERP APIs, to product prices and sentiment analysis, there are various services out there that make web scraping very straightforward. And they’re big business."

https://nordicapis.com/are-web-scraping-tools-overtaking-official-apis/

#APIs #WebScraping #SoftwareDevelopment #Programming #APIDocumentation #APIDesign #Python

"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

“The goal from starting out is to be able to create an API documentation suite from scratch. The minimal viable document, or the minimum the document must contain before it’s released, includes having all the calls covered, a description, even if only one sentence at this point, for every field and call, section overviews, call examples, and examples of each field. I suggest also creating a Postman collection file for each API suite. A Postman collection file is a complete set of all the requests and that each request may be run by clicking it; it’s a convenience to clients.

Being able to create that document indicates the writer’s proficiency in the mechanics of API documentation. There is a sense of accomplishment when achieving this and comfort with this process. And rightly so. They have the privilege now of calling themselves API documentation writers.”

https://robertdelwood.medium.com/starting-api-documentation-writers-obstacles-to-watch-out-for-e0907610466f

#TechnicalWriting #APIDocumentation #APIs #Programming #OpenAPI #DocsAsCode #SoftwareDevelopment #Postman