#apidocumentation — Public Fediverse posts

Has modern web documentation made API references worse? Linear pages instead of structured navigation—is that a step backward? Stefan Richthofer explores Javadoc, Doxygen, Sphinx & APIdia to show how API documentation can be easier to browse. Read: https://javapro.io/2026/07/28/meet-apidia-a-new-approach-to-api-documentation-browsing/

#Javadoc #Doxygen Sphinx #APIdia #APIDocumentation APIdia

Has modern web documentation made API references worse? Linear pages instead of structured navigation—is that a step backward? Stefan Richthofer explores Javadoc, Doxygen, Sphinx & APIdia to show how API documentation can be easier to browse. Read: https://javapro.io/2026/07/28/meet-apidia-a-new-approach-to-api-documentation-browsing/

#Javadoc #Doxygen Sphinx #APIdia #APIDocumentation APIdia

"That means that your API UX must be excellent, and the integration with the application must be flawless. It’s only at that point that you start seeing some signs of revenue. How, then, can you boost your returns without all this effort?

AX is the answer. It’s the new DX and API UX all in one. On steroids! In short, making AI agents your primary API consumers is now your goal. Let me repeat. AI agents are now your main API consumers. Everything else is just noise. And, to get there, you need to provide an excellent AX. The amount of API requests AI agents make is directly related to the number of prompts their users submit. On top of that, onboarding is practically taken care of with solutions like the OAuth 2.0 Dynamic Client Registration, or the more granular x402 Agentic Authorization Flow. Billing moves from a SaaS-oriented subscription model to a metered reality, where agents are the ones making the purchase decisions. In this new state of play, if agents have success completing tasks using your API, they’ll likely return. If your AX is poor, agents will churn and find a more efficient API to save tokens.

Offering a good AX starts with having all your documentation in a way a machine would understand."

https://apichangelog.substack.com/p/why-ax-is-the-new-standard-for-api-success

#APIs #AI #AIAgents #AgenticAI #AX #AgenticExperience #APIDocumentation #DX #DeveloperExperience #APIDesign

"That means that your API UX must be excellent, and the integration with the application must be flawless. It’s only at that point that you start seeing some signs of revenue. How, then, can you boost your returns without all this effort?

AX is the answer. It’s the new DX and API UX all in one. On steroids! In short, making AI agents your primary API consumers is now your goal. Let me repeat. AI agents are now your main API consumers. Everything else is just noise. And, to get there, you need to provide an excellent AX. The amount of API requests AI agents make is directly related to the number of prompts their users submit. On top of that, onboarding is practically taken care of with solutions like the OAuth 2.0 Dynamic Client Registration, or the more granular x402 Agentic Authorization Flow. Billing moves from a SaaS-oriented subscription model to a metered reality, where agents are the ones making the purchase decisions. In this new state of play, if agents have success completing tasks using your API, they’ll likely return. If your AX is poor, agents will churn and find a more efficient API to save tokens.

Offering a good AX starts with having all your documentation in a way a machine would understand."

https://apichangelog.substack.com/p/why-ax-is-the-new-standard-for-api-success

#APIs #AI #AIAgents #AgenticAI #AX #AgenticExperience #APIDocumentation #DX #DeveloperExperience #APIDesign

"That means that your API UX must be excellent, and the integration with the application must be flawless. It’s only at that point that you start seeing some signs of revenue. How, then, can you boost your returns without all this effort?

AX is the answer. It’s the new DX and API UX all in one. On steroids! In short, making AI agents your primary API consumers is now your goal. Let me repeat. AI agents are now your main API consumers. Everything else is just noise. And, to get there, you need to provide an excellent AX. The amount of API requests AI agents make is directly related to the number of prompts their users submit. On top of that, onboarding is practically taken care of with solutions like the OAuth 2.0 Dynamic Client Registration, or the more granular x402 Agentic Authorization Flow. Billing moves from a SaaS-oriented subscription model to a metered reality, where agents are the ones making the purchase decisions. In this new state of play, if agents have success completing tasks using your API, they’ll likely return. If your AX is poor, agents will churn and find a more efficient API to save tokens.

Offering a good AX starts with having all your documentation in a way a machine would understand."

https://apichangelog.substack.com/p/why-ax-is-the-new-standard-for-api-success

#APIs #AI #AIAgents #AgenticAI #AX #AgenticExperience #APIDocumentation #DX #DeveloperExperience #APIDesign

"That means that your API UX must be excellent, and the integration with the application must be flawless. It’s only at that point that you start seeing some signs of revenue. How, then, can you boost your returns without all this effort?

AX is the answer. It’s the new DX and API UX all in one. On steroids! In short, making AI agents your primary API consumers is now your goal. Let me repeat. AI agents are now your main API consumers. Everything else is just noise. And, to get there, you need to provide an excellent AX. The amount of API requests AI agents make is directly related to the number of prompts their users submit. On top of that, onboarding is practically taken care of with solutions like the OAuth 2.0 Dynamic Client Registration, or the more granular x402 Agentic Authorization Flow. Billing moves from a SaaS-oriented subscription model to a metered reality, where agents are the ones making the purchase decisions. In this new state of play, if agents have success completing tasks using your API, they’ll likely return. If your AX is poor, agents will churn and find a more efficient API to save tokens.

Offering a good AX starts with having all your documentation in a way a machine would understand."

https://apichangelog.substack.com/p/why-ax-is-the-new-standard-for-api-success

#APIs #AI #AIAgents #AgenticAI #AX #AgenticExperience #APIDocumentation #DX #DeveloperExperience #APIDesign

"That means that your API UX must be excellent, and the integration with the application must be flawless. It’s only at that point that you start seeing some signs of revenue. How, then, can you boost your returns without all this effort?

AX is the answer. It’s the new DX and API UX all in one. On steroids! In short, making AI agents your primary API consumers is now your goal. Let me repeat. AI agents are now your main API consumers. Everything else is just noise. And, to get there, you need to provide an excellent AX. The amount of API requests AI agents make is directly related to the number of prompts their users submit. On top of that, onboarding is practically taken care of with solutions like the OAuth 2.0 Dynamic Client Registration, or the more granular x402 Agentic Authorization Flow. Billing moves from a SaaS-oriented subscription model to a metered reality, where agents are the ones making the purchase decisions. In this new state of play, if agents have success completing tasks using your API, they’ll likely return. If your AX is poor, agents will churn and find a more efficient API to save tokens.

Offering a good AX starts with having all your documentation in a way a machine would understand."

https://apichangelog.substack.com/p/why-ax-is-the-new-standard-for-api-success

#APIs #AI #AIAgents #AgenticAI #AX #AgenticExperience #APIDocumentation #DX #DeveloperExperience #APIDesign

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

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

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

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

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

"Where SaaS might require you to set up a workflow manually, by configuring integrations and importing data, an AI agent that’s connected in the right way can be prompted conversationally. This might look like: “Match sales data with recurring customers, and identify those who have not purchased in more than three months so we can email them a discount code.”

That’s a powerful concept because it changes the focus from navigating a UI to using a system to execute natural language commands. But to work effectively, such a system requires structured access, permission-awareness, authentication, and orchestration across various platforms, and event-driven updates. In other words, it requires well-documented, low-latency, reliable APIs.
(...)
There’s a real possibility that we’re headed towards a headless world in which the UI is optional. The dashboard is no longer the product, but access to data is, which is something that many SaaS providers have been accumulating for years, sometimes even decades. Effective APIs continue to be the go-to mechanism for exposing data safely and securely, whether to humans or agents.

Which means that products with weak APIs risk becoming… well, invisible."

https://nordicapis.com/the-future-of-saas-is-apis-plus-ai-agents/

#AI #APIs #SaaS #AIAgents #APIDocumentation #LLMs #Programming #SoftwareDevelopment

"Where SaaS might require you to set up a workflow manually, by configuring integrations and importing data, an AI agent that’s connected in the right way can be prompted conversationally. This might look like: “Match sales data with recurring customers, and identify those who have not purchased in more than three months so we can email them a discount code.”

That’s a powerful concept because it changes the focus from navigating a UI to using a system to execute natural language commands. But to work effectively, such a system requires structured access, permission-awareness, authentication, and orchestration across various platforms, and event-driven updates. In other words, it requires well-documented, low-latency, reliable APIs.
(...)
There’s a real possibility that we’re headed towards a headless world in which the UI is optional. The dashboard is no longer the product, but access to data is, which is something that many SaaS providers have been accumulating for years, sometimes even decades. Effective APIs continue to be the go-to mechanism for exposing data safely and securely, whether to humans or agents.

Which means that products with weak APIs risk becoming… well, invisible."

https://nordicapis.com/the-future-of-saas-is-apis-plus-ai-agents/

#AI #APIs #SaaS #AIAgents #APIDocumentation #LLMs #Programming #SoftwareDevelopment

"Where SaaS might require you to set up a workflow manually, by configuring integrations and importing data, an AI agent that’s connected in the right way can be prompted conversationally. This might look like: “Match sales data with recurring customers, and identify those who have not purchased in more than three months so we can email them a discount code.”

That’s a powerful concept because it changes the focus from navigating a UI to using a system to execute natural language commands. But to work effectively, such a system requires structured access, permission-awareness, authentication, and orchestration across various platforms, and event-driven updates. In other words, it requires well-documented, low-latency, reliable APIs.
(...)
There’s a real possibility that we’re headed towards a headless world in which the UI is optional. The dashboard is no longer the product, but access to data is, which is something that many SaaS providers have been accumulating for years, sometimes even decades. Effective APIs continue to be the go-to mechanism for exposing data safely and securely, whether to humans or agents.

Which means that products with weak APIs risk becoming… well, invisible."

https://nordicapis.com/the-future-of-saas-is-apis-plus-ai-agents/

#AI #APIs #SaaS #AIAgents #APIDocumentation #LLMs #Programming #SoftwareDevelopment

"Where SaaS might require you to set up a workflow manually, by configuring integrations and importing data, an AI agent that’s connected in the right way can be prompted conversationally. This might look like: “Match sales data with recurring customers, and identify those who have not purchased in more than three months so we can email them a discount code.”

That’s a powerful concept because it changes the focus from navigating a UI to using a system to execute natural language commands. But to work effectively, such a system requires structured access, permission-awareness, authentication, and orchestration across various platforms, and event-driven updates. In other words, it requires well-documented, low-latency, reliable APIs.
(...)
There’s a real possibility that we’re headed towards a headless world in which the UI is optional. The dashboard is no longer the product, but access to data is, which is something that many SaaS providers have been accumulating for years, sometimes even decades. Effective APIs continue to be the go-to mechanism for exposing data safely and securely, whether to humans or agents.

Which means that products with weak APIs risk becoming… well, invisible."

https://nordicapis.com/the-future-of-saas-is-apis-plus-ai-agents/

#AI #APIs #SaaS #AIAgents #APIDocumentation #LLMs #Programming #SoftwareDevelopment

"Where SaaS might require you to set up a workflow manually, by configuring integrations and importing data, an AI agent that’s connected in the right way can be prompted conversationally. This might look like: “Match sales data with recurring customers, and identify those who have not purchased in more than three months so we can email them a discount code.”

That’s a powerful concept because it changes the focus from navigating a UI to using a system to execute natural language commands. But to work effectively, such a system requires structured access, permission-awareness, authentication, and orchestration across various platforms, and event-driven updates. In other words, it requires well-documented, low-latency, reliable APIs.
(...)
There’s a real possibility that we’re headed towards a headless world in which the UI is optional. The dashboard is no longer the product, but access to data is, which is something that many SaaS providers have been accumulating for years, sometimes even decades. Effective APIs continue to be the go-to mechanism for exposing data safely and securely, whether to humans or agents.

Which means that products with weak APIs risk becoming… well, invisible."

https://nordicapis.com/the-future-of-saas-is-apis-plus-ai-agents/

#AI #APIs #SaaS #AIAgents #APIDocumentation #LLMs #Programming #SoftwareDevelopment

"The number of APIs has been increasing year-over-year, as they’re the infrastructure that makes the majority of modern digital architecture possible. Given that everything from AI to SaaS involves APIs at their core, it’s not the greatest shock that 78% of organizations don’t even know how many APIs they manage. A report from F5 finds that large companies manage an average of 1,400 APIs, with some having as many as 10,000. Even smaller companies can have as many as 200.

In short, barely anybody works with a single API. Managing multiple APIs is no longer optional for many enterprises — it’s simply a fact. But many organizations don’t have a unified plan for managing their APIs, leading to a disparate API portfolio with various styles and tools. Haphazard approaches and poor governance can even produce shadow APIs.

In light of this reality, we’ve put together a few tips for managing multiple APIs. We’ll cover tips on cataloging APIs, aligning on consistent security controls and governance, and more to help manage different APIs across an organization."

https://nordicapis.com/6-tips-for-managing-multiple-apis/

#API #APIs #APIGateways #APIGovernance #APIDocumentation #SoftwareDevelopment #Programming

"The number of APIs has been increasing year-over-year, as they’re the infrastructure that makes the majority of modern digital architecture possible. Given that everything from AI to SaaS involves APIs at their core, it’s not the greatest shock that 78% of organizations don’t even know how many APIs they manage. A report from F5 finds that large companies manage an average of 1,400 APIs, with some having as many as 10,000. Even smaller companies can have as many as 200.

In short, barely anybody works with a single API. Managing multiple APIs is no longer optional for many enterprises — it’s simply a fact. But many organizations don’t have a unified plan for managing their APIs, leading to a disparate API portfolio with various styles and tools. Haphazard approaches and poor governance can even produce shadow APIs.

In light of this reality, we’ve put together a few tips for managing multiple APIs. We’ll cover tips on cataloging APIs, aligning on consistent security controls and governance, and more to help manage different APIs across an organization."

https://nordicapis.com/6-tips-for-managing-multiple-apis/

#API #APIs #APIGateways #APIGovernance #APIDocumentation #SoftwareDevelopment #Programming

"The number of APIs has been increasing year-over-year, as they’re the infrastructure that makes the majority of modern digital architecture possible. Given that everything from AI to SaaS involves APIs at their core, it’s not the greatest shock that 78% of organizations don’t even know how many APIs they manage. A report from F5 finds that large companies manage an average of 1,400 APIs, with some having as many as 10,000. Even smaller companies can have as many as 200.

In short, barely anybody works with a single API. Managing multiple APIs is no longer optional for many enterprises — it’s simply a fact. But many organizations don’t have a unified plan for managing their APIs, leading to a disparate API portfolio with various styles and tools. Haphazard approaches and poor governance can even produce shadow APIs.

In light of this reality, we’ve put together a few tips for managing multiple APIs. We’ll cover tips on cataloging APIs, aligning on consistent security controls and governance, and more to help manage different APIs across an organization."

https://nordicapis.com/6-tips-for-managing-multiple-apis/

#API #APIs #APIGateways #APIGovernance #APIDocumentation #SoftwareDevelopment #Programming

"The number of APIs has been increasing year-over-year, as they’re the infrastructure that makes the majority of modern digital architecture possible. Given that everything from AI to SaaS involves APIs at their core, it’s not the greatest shock that 78% of organizations don’t even know how many APIs they manage. A report from F5 finds that large companies manage an average of 1,400 APIs, with some having as many as 10,000. Even smaller companies can have as many as 200.

In short, barely anybody works with a single API. Managing multiple APIs is no longer optional for many enterprises — it’s simply a fact. But many organizations don’t have a unified plan for managing their APIs, leading to a disparate API portfolio with various styles and tools. Haphazard approaches and poor governance can even produce shadow APIs.

In light of this reality, we’ve put together a few tips for managing multiple APIs. We’ll cover tips on cataloging APIs, aligning on consistent security controls and governance, and more to help manage different APIs across an organization."

https://nordicapis.com/6-tips-for-managing-multiple-apis/

#API #APIs #APIGateways #APIGovernance #APIDocumentation #SoftwareDevelopment #Programming

"The number of APIs has been increasing year-over-year, as they’re the infrastructure that makes the majority of modern digital architecture possible. Given that everything from AI to SaaS involves APIs at their core, it’s not the greatest shock that 78% of organizations don’t even know how many APIs they manage. A report from F5 finds that large companies manage an average of 1,400 APIs, with some having as many as 10,000. Even smaller companies can have as many as 200.

In short, barely anybody works with a single API. Managing multiple APIs is no longer optional for many enterprises — it’s simply a fact. But many organizations don’t have a unified plan for managing their APIs, leading to a disparate API portfolio with various styles and tools. Haphazard approaches and poor governance can even produce shadow APIs.

In light of this reality, we’ve put together a few tips for managing multiple APIs. We’ll cover tips on cataloging APIs, aligning on consistent security controls and governance, and more to help manage different APIs across an organization."

https://nordicapis.com/6-tips-for-managing-multiple-apis/

#API #APIs #APIGateways #APIGovernance #APIDocumentation #SoftwareDevelopment #Programming

EXCLUSIVE: Consistency for the Aptivi Newsroom and API docs design

Last week, we have reported that the June 2026 redesign for the Aptivi Blog had finished in two stages: design and structure. This took a lot of effort into ensuring that responsive design was applied across all form factors, including mobile phones and tablets. This was a project that was planned to fix problems that plagued the older design that we revealed back on February 2026 as part of the bigger milestone.

As we have gathered great feedback, we’d like to extend this effort to include both the API documentation of our projects that use .NET and the Aptivi Newsroom website. We will perform the necessary changes to ensure that our design is:

• Consistent: We will update both sites to be consistent with our new design language, including colors and other element properties.
• Cohesive: We will update both sites to ensure that they become readable across all form factors.
• Reliable: We will update both sites to make the design elements, such as text and images, adapt to different form factors, while making sure that problems related to design are resolved.

This design change, however, has no schedule, so it will slowly roll out according to the results of our experiments. If things go well, we will start rolling it out to a small batch, such as Nitrocid and Terminaux, before extending to larger batches to make sure that any last-minute bugs with the design can be caught early.

Aptivi Newsroom will get the updated design first, then the API documentation design update will come in tiers, which will span for three weeks, as we keep testing the new design to ensure that it reliably achieves our goal.

Currently, there is no set date as to when we’ll start rolling out the changes, but we will showcase them to you in a separate Aptivi Newsroom article once we start pushing the design updates.

EXCLUSIVE: Consistency for the Aptivi Newsroom and API docs design

Last week, we have reported that the June 2026 redesign for the Aptivi Blog had finished in two stages: design and structure. This took a lot of effort into ensuring that responsive design was applied across all form factors, including mobile phones and tablets. This was a project that was planned to fix problems that plagued the older design that we revealed back on February 2026 as part of the bigger milestone.

As we have gathered great feedback, we’d like to extend this effort to include both the API documentation of our projects that use .NET and the Aptivi Newsroom website. We will perform the necessary changes to ensure that our design is:

• Consistent: We will update both sites to be consistent with our new design language, including colors and other element properties.
• Cohesive: We will update both sites to ensure that they become readable across all form factors.
• Reliable: We will update both sites to make the design elements, such as text and images, adapt to different form factors, while making sure that problems related to design are resolved.

This design change, however, has no schedule, so it will slowly roll out according to the results of our experiments. If things go well, we will start rolling it out to a small batch, such as Nitrocid and Terminaux, before extending to larger batches to make sure that any last-minute bugs with the design can be caught early.

Aptivi Newsroom will get the updated design first, then the API documentation design update will come in tiers, which will span for three weeks, as we keep testing the new design to ensure that it reliably achieves our goal.

Currently, there is no set date as to when we’ll start rolling out the changes, but we will showcase them to you in a separate Aptivi Newsroom article once we start pushing the design updates.

EXCLUSIVE: Consistency for the Aptivi Newsroom and API docs design

Last week, we have reported that the June 2026 redesign for the Aptivi Blog had finished in two stages: design and structure. This took a lot of effort into ensuring that responsive design was applied across all form factors, including mobile phones and tablets. This was a project that was planned to fix problems that plagued the older design that we revealed back on February 2026 as part of the bigger milestone.

As we have gathered great feedback, we’d like to extend this effort to include both the API documentation of our projects that use .NET and the Aptivi Newsroom website. We will perform the necessary changes to ensure that our design is:

• Consistent: We will update both sites to be consistent with our new design language, including colors and other element properties.
• Cohesive: We will update both sites to ensure that they become readable across all form factors.
• Reliable: We will update both sites to make the design elements, such as text and images, adapt to different form factors, while making sure that problems related to design are resolved.

This design change, however, has no schedule, so it will slowly roll out according to the results of our experiments. If things go well, we will start rolling it out to a small batch, such as Nitrocid and Terminaux, before extending to larger batches to make sure that any last-minute bugs with the design can be caught early.

Aptivi Newsroom will get the updated design first, then the API documentation design update will come in tiers, which will span for three weeks, as we keep testing the new design to ensure that it reliably achieves our goal.

Currently, there is no set date as to when we’ll start rolling out the changes, but we will showcase them to you in a separate Aptivi Newsroom article once we start pushing the design updates.

EXCLUSIVE: Consistency for the Aptivi Newsroom and API docs design

Last week, we have reported that the June 2026 redesign for the Aptivi Blog had finished in two stages: design and structure. This took a lot of effort into ensuring that responsive design was applied across all form factors, including mobile phones and tablets. This was a project that was planned to fix problems that plagued the older design that we revealed back on February 2026 as part of the bigger milestone.

As we have gathered great feedback, we’d like to extend this effort to include both the API documentation of our projects that use .NET and the Aptivi Newsroom website. We will perform the necessary changes to ensure that our design is:

• Consistent: We will update both sites to be consistent with our new design language, including colors and other element properties.
• Cohesive: We will update both sites to ensure that they become readable across all form factors.
• Reliable: We will update both sites to make the design elements, such as text and images, adapt to different form factors, while making sure that problems related to design are resolved.

This design change, however, has no schedule, so it will slowly roll out according to the results of our experiments. If things go well, we will start rolling it out to a small batch, such as Nitrocid and Terminaux, before extending to larger batches to make sure that any last-minute bugs with the design can be caught early.

Aptivi Newsroom will get the updated design first, then the API documentation design update will come in tiers, which will span for three weeks, as we keep testing the new design to ensure that it reliably achieves our goal.

Currently, there is no set date as to when we’ll start rolling out the changes, but we will showcase them to you in a separate Aptivi Newsroom article once we start pushing the design updates.

EXCLUSIVE: Consistency for the Aptivi Newsroom and API docs design

Last week, we have reported that the June 2026 redesign for the Aptivi Blog had finished in two stages: design and structure. This took a lot of effort into ensuring that responsive design was applied across all form factors, including mobile phones and tablets. This was a project that was planned to fix problems that plagued the older design that we revealed back on February 2026 as part of the bigger milestone.

As we have gathered great feedback, we’d like to extend this effort to include both the API documentation of our projects that use .NET and the Aptivi Newsroom website. We will perform the necessary changes to ensure that our design is:

• Consistent: We will update both sites to be consistent with our new design language, including colors and other element properties.
• Cohesive: We will update both sites to ensure that they become readable across all form factors.
• Reliable: We will update both sites to make the design elements, such as text and images, adapt to different form factors, while making sure that problems related to design are resolved.

This design change, however, has no schedule, so it will slowly roll out according to the results of our experiments. If things go well, we will start rolling it out to a small batch, such as Nitrocid and Terminaux, before extending to larger batches to make sure that any last-minute bugs with the design can be caught early.

Aptivi Newsroom will get the updated design first, then the API documentation design update will come in tiers, which will span for three weeks, as we keep testing the new design to ensure that it reliably achieves our goal.

Currently, there is no set date as to when we’ll start rolling out the changes, but we will showcase them to you in a separate Aptivi Newsroom article once we start pushing the design updates.

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

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

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

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

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

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

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

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

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

"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

"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

"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

"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

"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

"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