Miguel Afonso Caetano<p>"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.</p><p>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."</p><p><a href="https://robertdelwood.medium.com/writing-for-humans-an-api-documentation-writer-writes-3c51a6ea87a5" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">robertdelwood.medium.com/writi</span><span class="invisible">ng-for-humans-an-api-documentation-writer-writes-3c51a6ea87a5</span></a></p><p><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/API" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>API</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalCommunication</span></a></p>
eupolicy.social is one of the many independent Mastodon servers you can use to participate in the fediverse.
This Mastodon server is a friendly and respectful discussion space for people working in areas related to EU policy. When you request to create an account, please tell us something about you.
Administered by:
Server stats:
192active users
eupolicy.social: About · Profiles directory · Privacy policy
Mastodon: About · Get the app · Keyboard shortcuts · View source code · v4.4.1
#apidocumentation
1 post · 1 participant · 0 posts today
Miguel Afonso Caetano<p>“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.</p><p>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.”</p><p><a href="https://robertdelwood.medium.com/starting-api-documentation-writers-obstacles-to-watch-out-for-e0907610466f" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">robertdelwood.medium.com/start</span><span class="invisible">ing-api-documentation-writers-obstacles-to-watch-out-for-e0907610466f</span></a></p><p><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/Programming" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Programming</span></a> <a href="https://tldr.nettime.org/tags/OpenAPI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>OpenAPI</span></a> <a href="https://tldr.nettime.org/tags/DocsAsCode" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DocsAsCode</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a> <a href="https://tldr.nettime.org/tags/Postman" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Postman</span></a></p>
Miguel Afonso Caetano<p>"How to leverage documentation effectively in Cursor through prompting, external sources, and internal context<br><br>Why documentation matters</p><p>Documentation provides current, accurate context. Without it, models use outdated or incomplete training data. Documentation helps models understand things like:</p><p>- Current APIs and parameters<br>- Best practices<br>- Organization conventions<br>- Domain terminology</p><p>And much more. Read on to learn how to use documentation right in Cursor without having to context switch."</p><p><a href="https://docs.cursor.com/guides/advanced/working-with-documentation" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">docs.cursor.com/guides/advance</span><span class="invisible">d/working-with-documentation</span></a></p><p><a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>AI</span></a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>GenerativeAI</span></a> <a href="https://tldr.nettime.org/tags/Cursor" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Cursor</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/Documentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Documentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a></p>
Miguel Afonso Caetano<p>"Let me be blunt.</p><p>If your startup offers APIs and you don’t have a portal, you’re lighting developer acquisition money on fire. 💵 🧯🚒</p><p>Here’s what a good portal actually does:</p><p>Shortens time-to-value: faster POCs, faster adoption.</p><p>Reduces support tickets: devs can find what they need.</p><p>Builds trust: your API feels stable, documented, and ready.</p><p>Increases conversion: when docs show how easy it is to integrate, not just tell.</p><p>Still sending PDF onboarding packets to partners?</p><p>C’mon, boo. 🥲"</p><p><a href="https://www.quetzalliwrites.com/newsletters/developer-portals-dev-friendly-or-dev-frustrating" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://www.</span><span class="ellipsis">quetzalliwrites.com/newsletter</span><span class="invisible">s/developer-portals-dev-friendly-or-dev-frustrating</span></a></p><p><a href="https://tldr.nettime.org/tags/DevPortals" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DevPortals</span></a> <a href="https://tldr.nettime.org/tags/DeveloperPortals" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DeveloperPortals</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/API" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>API</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriter" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriter</span></a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalCommunication</span></a></p>
Miguel Afonso Caetano<p>"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.</p><p>Here is some more context to help you decide on an approach and get started."</p><p><a href="https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">gist.github.com/briandominick/</span><span class="invisible">3ffab6be460fbde799aa34e0a42a4299</span></a></p><p><a href="https://tldr.nettime.org/tags/API" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>API</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIDesign" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDesign</span></a> <a href="https://tldr.nettime.org/tags/REST" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>REST</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/OpenAPI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>OpenAPI</span></a> <a href="https://tldr.nettime.org/tags/DocsAsCode" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DocsAsCode</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalCommunication</span></a></p>
Miguel Afonso Caetano<p>"Getting to this point isn’t unusual. Clients clearly think they’re making the call correctly, or else they would fix the endpoint themselves. Some misspellings are difficult to catch. The enum USER_RETREIVE may not be noticed from USER_RETRIEVE, especially if picking it from a list. Misspellings happen and they’re not always caught before making it to the contract. As an aside, that’s why it’s important writers routinely check development’s changes. This applies, too, to our testing calls in Postman, where manually entering endpoints and values are more pervasive.</p><p>The reason this isn’t caught is simple: We’re not expecting it.</p><p>For our testing, the call is made and we get results. We may even spot check some of them. But generally, results aren’t examined that closely. For instance, how often do you so carefully examine a returned list of 50 or 100 items? You check may check that the objects are complete but not that the list conforms to the search criteria.</p><p>The reason this happens is because of an intentional behavior on the server. This behavior is called Lenient Handling or Strict Handling."</p><p><a href="https://robertdelwood.medium.com/understanding-query-parameter-handling-in-rest-calls-1821e0c3fa8c" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">robertdelwood.medium.com/under</span><span class="invisible">standing-query-parameter-handling-in-rest-calls-1821e0c3fa8c</span></a></p><p><a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/RESTAPIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>RESTAPIs</span></a> <a href="https://tldr.nettime.org/tags/Rest" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Rest</span></a> <a href="https://tldr.nettime.org/tags/APITesting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APITesting</span></a> <a href="https://tldr.nettime.org/tags/APIDesign" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDesign</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a></p>
Miguel Afonso Caetano<p>“Fortunately, I think there’s a good alternative to the dismal picture of brain-dead tech writers pressing buttons on AI machines and passing the content to SMEs for review. That alternative is to focus on what AI algorithms can’t do (at least not with a few button clicks). In this revised approach, tech writers offload the simple tasks to AI tools to fix while focusing their real time and energy on more complex, ambitious tasks that are beyond the straightforward capabilities of AI tools.</p><p>When I say beyond AI capabilities, I still mean AI tools might assist or augment tech writers in the work; it’s just that the tasks aren’t as simple as the mechanical tasks of fixing doc bugs that I described earlier (e.g., “what’s the issue? what’s the fix?”).</p><p>For example, when I set about creating complex tree diagrams showing all elements in an API, this was a new kind of documentation that hadn’t been done before at my company. It became an instant hit and one that proved challenging to maintain and grow and fix, but still worthwhile. (In fact, in a chat with a product manager last week, he wondered if our tree diagram page wasn’t the most popular page in our documentation.)</p><p>If we focused more on these sophisticated tasks (beyond click-button AI), I think tech writers could have a brighter future.”</p><p><a href="https://idratherbewriting.com/blog/recursive-self-improvement-complex-tasks" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">idratherbewriting.com/blog/rec</span><span class="invisible">ursive-self-improvement-complex-tasks</span></a></p><p><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>AI</span></a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>GenerativeAI</span></a> <a href="https://tldr.nettime.org/tags/LLMs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>LLMs</span></a> <a href="https://tldr.nettime.org/tags/Docs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Docs</span></a></p>
Miguel Afonso Caetano<p>“A README acts as the front door to an API, offering consumers brief and sufficient information to get started. A full documentation is a place where consumers go to when they need to find information about any detail of the API. Having one doesn't mean you shouldn't have the other. But, having a README is, in my opinion, the very minimum you can do if you're serious about your API. And, at the very minimum, there are three elements I'd consider.”</p><p><a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/Markdown" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Markdown</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/Git" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Git</span></a> <a href="https://tldr.nettime.org/tags/DocsAsCode" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DocsAsCode</span></a> </p><p><a href="https://apichangelog.substack.com/p/three-elements-of-a-good-api-readme" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">apichangelog.substack.com/p/th</span><span class="invisible">ree-elements-of-a-good-api-readme</span></a></p>
Miguel Afonso Caetano<p>"A quick start guide offers concise step-by-step instructions to help users quickly get started with a product, service, or tool. In the context of API documentation, a quick start guide covers the minimal steps required for developers to make their first API call successfully. It typically provides steps such as how to create an account, where to locate API keys or credentials, how to authenticate, example code to make a basic API call, a way to display the response, and troubleshooting tips. The goal is to deliver a quick win to developers and provide a foundation to integrate with your API."</p><p><a href="https://www.apimatic.io/blog/how-to-design-a-quick-start-guide-for-your-api" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://www.</span><span class="ellipsis">apimatic.io/blog/how-to-design</span><span class="invisible">-a-quick-start-guide-for-your-api</span></a></p><p><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/GettingStarted" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>GettingStarted</span></a> <a href="https://tldr.nettime.org/tags/Tutorials" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Tutorials</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a> <a href="https://tldr.nettime.org/tags/DE" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DE</span></a> <a href="https://tldr.nettime.org/tags/DeveloperExperience" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DeveloperExperience</span></a></p>
Miguel Afonso Caetano<p>"Normally, you don't visit your own API documentation that often, right? I mean, if you already know how your API works, why would you want to consult its documentation? Conversely, there's a place you visit—or should visit—very often, with information you care about your API. I assume you have an API dashboard where you can review metrics such as the ones I described earlier. Usually, the dashboard lives close to the API gateway, or somewhere where other company-wide observability tools reside. What I'm proposing here, in short, is that the API documentation can be the best place to present those metrics to you, the producer.</p><p>Being able to see the metrics you care about right near the documentation for each part of your API feels refreshing. You could, for instance, be looking at the reference of one operation and immediately see its usage trend, the error rate, the number of active consumers in the last hour, and so on. What's more, some of the information visible only to you could also be actionable. You could, for instance, open the pending support requests to see what the top complaints are. Or, you could immediately check why there's such a percentage of errors on one single operation.</p><p>While most information would be restricted to you, the producer, I argue that some things could even be openly shared with your API consumers. Imagine being a consumer and seeing a list of "popular" API operations right on the documentation. Or understanding if a certain operation is producing a high error rate. All these things could be easily available in the API documentation."</p><p><a href="https://apichangelog.substack.com/p/producer-oriented-api-documentation" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">apichangelog.substack.com/p/pr</span><span class="invisible">oducer-oriented-api-documentation</span></a></p><p><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/APIMetrics" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIMetrics</span></a> <a href="https://tldr.nettime.org/tags/APIAnalytics" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIAnalytics</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a></p>
Miguel Afonso Caetano<p>"Similar to Wood’s conviction that AI’s transformative potential doesn’t come from simple tasks like writing emails, tech writers will likely find conviction when they go beyond fixing simple grammar errors to using AI for developing conceptual articles, generating release notes, or understanding connections across disparate API products.</p><p>One of my colleagues compared using AI like learning to play an instrument—it’s one thing to have an intellectual understanding about the instrument and notes, but knowing how to play an instrument well is entirely different. It takes practice, experimentation, learning, diligence, and time. Maybe too many tech writers feel that AI should provide a push-button solution to creating documentation effortlessly (a misguided perception based on too much AI hype). When pushing that button doesn’t magically produce great docs, perhaps they become cynical and dismissive?"</p><p><a href="https://idratherbewriting.com/blog/trends-predictions-2025-tech-comm" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">idratherbewriting.com/blog/tre</span><span class="invisible">nds-predictions-2025-tech-comm</span></a></p><p><a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>AI</span></a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>GenerativeAI</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalCommunication</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/PromptEngineering" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>PromptEngineering</span></a> <a href="https://tldr.nettime.org/tags/TechComm" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechComm</span></a></p>
Miguel Afonso Caetano<p>"The quality of job descriptions varies wildly. That means how the job is described, the components of the job, and expertise expected for each component. The descriptions are better for the common job types, such as project and product managers, developers, and sales. Companies know what those are and have experience hiring those.</p><p>All that falls apart when it comes to writing, of any type, and specifically API documentation writers. CEOs, who I love to vilify for this reason, generally don’t understand technical writing and technical writers. To them, and that attitude often trickles down the table of organization, see copy, marketing, content, and technical writing as the same and interchangeable. I believe this causes the low pay rates, because we’re seen as a commodity, going at market rate. A doctor with 15 years of experience is treated as an expert. A writer with 15 years of experience competes in the marketplace with junior writers. A shame for sure. I digress some but that needed to be pointed out.</p><p>There is information to be mined from bad job descriptions, if you know what to look for and know how to use that information."</p><p><a href="https://robertdelwood.medium.com/reading-api-documentation-writers-job-descriptions-92124e5d9008" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">robertdelwood.medium.com/readi</span><span class="invisible">ng-api-documentation-writers-job-descriptions-92124e5d9008</span></a></p><p><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a></p>
Miguel Afonso Caetano<p>"The only goal of API documentation has to be for “great documentation.” I define that as documentation so clear so it defies misunderstanding. Why would it be anything else? While it sounds like a lofty goal, it’s easily obtainable and within everyone’s reach. It begins by thinking like a developer. API documentation writers have to move away from thinking like a technical writer.</p><p>When documenting strings, many writers just think about this as little more as characters within quotes, or as a combined set of characters. The following are two examples commonly documented for strings. In a moment, you’ll see how inadequate these really are."</p><p><a href="https://robertdelwood.medium.com/the-truth-about-describing-strings-932c28bbde22" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">robertdelwood.medium.com/the-t</span><span class="invisible">ruth-about-describing-strings-932c28bbde22</span></a></p><p><a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a> <a href="https://tldr.nettime.org/tags/Programming" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Programming</span></a></p>
Miguel Afonso Caetano<p>"In short, APIs are how businesses speak to one another. Breaking this oath with a poor integration experience is a surefire way to reduce your business potential. By utilizing a source of truth and baking a specification-first approach into your API development and documentation practices, you more clearly communicate changes, reducing the possibility of broken clients and promoting forward compatibility. Great API products must be well-described, easy to understand, and predictable in the long run.</p><p>In the end, the business effects of specification-driven development are manifold. Whether you're building RESTful, GraphQL, or event-driven partner services, having reliable API documentation is important to compete in the digital economy. This consistency equates to a better partner experience, leading to stickier partners and less customer churn. By enabling smoother integrations and reducing frustration, spec-first documentation directly contributes to partner retention and loyalty, which ultimately drives revenue growth."</p><p><a href="https://bump.sh/blog/how-spec-first-api-documentation-aids-partner-integration" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">bump.sh/blog/how-spec-first-ap</span><span class="invisible">i-documentation-aids-partner-integration</span></a></p><p><a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/SpecFirst" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SpecFirst</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/Docs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Docs</span></a> <a href="https://tldr.nettime.org/tags/DeveloperExperience" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DeveloperExperience</span></a> <a href="https://tldr.nettime.org/tags/DocsAsCode" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DocsAsCode</span></a></p>
Miguel Afonso Caetano<p>"So, if developers aren’t going to use Try Its, what harm is there for including them? They can just ignore them, right? Perhaps, but there’s more to it.</p><p>It takes up valuable screen real estate (the right corner above the fold). Writers need to optimize the developer experience, even to the point of minimizing eye movements. Make it easy to find details. That space could be used more productively.</p><p>We “should know” but we don’t. This segues into the real reason. It demonstrates that writers don’t know the developer experience. Let’s be blunt. We’re delivering documentation suites that have not been tested properly, calls that are unlikely to have been tested, and tools developers don’t use. Not understanding these issues is the fundamental reason writers also need developer experience. Writers simply can’t empathize with own audiences, which means we supplying developers with inadequate and incomplete tools and documentation. This is a real concern.</p><p>This is not a condemnation. Quite the opposite. API documentation writers need to empathize with developers. Writers do this by treating this as a craft, learn a little about development each day, and move slowly along the experience spectrum towards the developer’s end. Learn a language. It doesn’t matter which one. Java, JavaScript, to DOS batch commands, UNIX command line programming, Word macros, Python, or even AutoHotKey*. All of these have programming concepts and that’s what matters. Learn about them, which requires using an API guide, craft statements, and debug them is at the heart of the matter."</p><p><a href="https://robertdelwood.medium.com/why-i-dont-like-try-it-f44112ed1b6d" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">robertdelwood.medium.com/why-i</span><span class="invisible">-dont-like-try-it-f44112ed1b6d</span></a></p><p><a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a></p>
Miguel Afonso Caetano<p>"A handful of root causes are likely behind API drift. One standout point is the simple fact that API documentation is typically incomplete. Only 10% of organizations fully document their APIs, found a 2023 EMA report. Without a strong documentation culture or comprehensive API inventory management, it’s more common to see a disorganized use of service descriptions.</p><p>Furthermore, many groups are still early on in their API governance strategies. As the number of APIs increases within a company, those without established standards for maintaining the API lifecycle are more likely to experience incompatibilities or even see services turn into shadow or zombie APIs.</p><p>According to Lorna Mitchell, VP of Developer Experience at Redocly, API drift is intrinsically tied to a lack of comprehensive testing. Drift can occur for design-first APIs if there aren’t clear tests of whether what is built actually matches what’s described. This is a problem that can easily become endemic, she says. “Code gets duplicated, and the chasm widens.”"</p><p><a href="https://nordicapis.com/understanding-the-root-causes-of-api-drift/" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">nordicapis.com/understanding-t</span><span class="invisible">he-root-causes-of-api-drift/</span></a></p><p><a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIDesign" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDesign</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/APIDrift" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDrift</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a> <a href="https://tldr.nettime.org/tags/Programming" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Programming</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/OpenAPI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>OpenAPI</span></a> <a href="https://tldr.nettime.org/tags/Swagger" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Swagger</span></a></p>
Miguel Afonso Caetano<p>"I’ve outlined each step of my process to illustrate the iterative nature of working with AI tools, which become like power tools in the hands of skilled writers. Simply asking the AI to generate a final draft of the documentation based only on the original meeting transcript would likely lead to a poor result, prompting the writer to mistakenly conclude that AI tools are unsuitable for documentation tasks like this. But by using an approach that involves multiple processes and iterative drafts, the AI tools produce a more intelligent outcome.</p><p>Some might argue that this extensive iterative process — with its numerous drafts, prompts, and reviews — negates the time-saving benefits of using AI tools. Why not just write it yourself from scratch? However, I still think writing the draft from scratch would be more time-consuming and be less accurate. Although it seems like a lot of iterative steps, remember that the AI performs each step in a matter of seconds. Additionally, writing sentences from scratch consumes a lot of mental effort, whereas using AI tools is a more mechanical task with only judgement and editorial acumen needed. For instance, I could likely watch a football game or a TV show while guiding the AI through these steps. In contrast, drafting the content manually would likely exhaust me within two hours."</p><p><a href="https://idratherbewriting.com/ai/prompt-engineering-iterative-chain-of-thought.html" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">idratherbewriting.com/ai/promp</span><span class="invisible">t-engineering-iterative-chain-of-thought.html</span></a></p><p><a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>AI</span></a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>GenerativeAI</span></a> <a href="https://tldr.nettime.org/tags/PromptEngineering" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>PromptEngineering</span></a> <a href="https://tldr.nettime.org/tags/LLMs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>LLMs</span></a> <a href="https://tldr.nettime.org/tags/Chatbots" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Chatbots</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDevelopment</span></a></p>
Miguel Afonso Caetano<p><a href="https://tldr.nettime.org/tags/APIDesign" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDesign</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/APIGovernance" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIGovernance</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/DX" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DX</span></a> <a href="https://tldr.nettime.org/tags/DeveloperExperience" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DeveloperExperience</span></a>: "Most enterprises face a widening API portfolio with an increasing number of API design styles and standards. “Almost all organizations are doing this,” says Brian Otten, VP of digital transformation catalysts at Axway. “I recently talked to a large food retailer that wants to see REST APIs alongside event-based resources and GraphQL,” Otten says.</p><p>In addition to the patchwork of API styles, most companies use multiple API gateways or management tools simultaneously. “We are at a point where organizations who already have API management solutions are buying API management solutions,” says Mark O’Neill, VP analyst at Gartner. O’Neill notes that in some cases, this is to replace the current platform, but in many situations, it’s cumulative.</p><p>In this multi-paradigm world, API governance is emerging as a key element for bridging disparate styles and avoiding the pains of a sprawling technical portfolio. According to API industry experts, governance will require a greater emphasis on documentation, centralizing common patterns across the organization, consolidating tools, and building internal platforms that improve the developer experience."</p><p><a href="https://www.infoworld.com/article/3529600/how-do-you-govern-a-sprawling-disparate-api-portfolio.html" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://www.</span><span class="ellipsis">infoworld.com/article/3529600/</span><span class="invisible">how-do-you-govern-a-sprawling-disparate-api-portfolio.html</span></a></p>
Miguel Afonso Caetano<p>🚀 Struggling with fragmented API documentation across multiple products?</p><p>Want to improve your developer experience and reduce support requests?</p><p>Check the presentation below where I unveil a strategic approach to unify and enhance API documentation tailored for large organizations facing scattered API docs and inconsistent standards across products. 📚</p><p>In this presentation, I cover:</p><p>✅ Auditing existing documentation for consistency.</p><p>✅ Creating a unified style guide and using automated tools.</p><p>✅ Building a centralized documentation portal.</p><p>✅ Collaborating with diverse stakeholders for a cohesive strategy.</p><p>If you're a documentation manager, a product manager, or a technical writer looking to streamline your API docs and empower internal teams and external developers, this is for you!</p><p>If you have any questions, doubts, suggestions, or feedback, feel free to leave a comment.</p><p><a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a> <a href="https://tldr.nettime.org/tags/DeveloperExperience" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DeveloperExperience</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/ProductManagement" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ProductManagement</span></a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIs</span></a> <a href="https://tldr.nettime.org/tags/DX" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DX</span></a> <a href="https://tldr.nettime.org/tags/DeveloperExperience" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DeveloperExperience</span></a> <a href="https://tldr.nettime.org/tags/TechDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechDocs</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> </p><p><a href="https://drive.google.com/file/d/1CyPzuUrz5S8uEIkj2YfXMts_41kQBOHM/view?usp=drive_link" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">drive.google.com/file/d/1CyPzu</span><span class="invisible">Urz5S8uEIkj2YfXMts_41kQBOHM/view?usp=drive_link</span></a></p>
Miguel Afonso Caetano<p><a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>AI</span></a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>GenerativeAI</span></a> <a href="https://tldr.nettime.org/tags/NotebookLM" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>NotebookLM</span></a> <a href="https://tldr.nettime.org/tags/Podcasts" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Podcasts</span></a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>APIDocumentation</span></a>: "I’ve wondered about more explicit ways to use NotebookLM podcasts for documentation. This weekend I made about 10 podcasts (each notebook has different content, generating its own audio file). The topics I tried were the following:</p><p>- An SDK overview<br>- Each API section in the SDK<br>- An engineering report about two of the APIs, noting quality measures<br>- An organizational strategy/vision document<br>- A biweekly update on a project<br>- A code sample<br>- A highly technical conceptual article</p><p>Each of these podcasts was impressively educational and interesting. With the technical conceptual article, I found myself thinking, “Oh, is that what that article was all about?” I suddenly understood it. With the code sample, I wondered how the hosts managed to expand their conversation into so many other details. How did they unpack all that from a single code sample? The engineering report was probably the most interesting. What I initially overlooked as a boring software quality report, the hosts turned it into a fascinating and alarming conversation. It made me want to re-read that report in much more detail.</p><p>In about an hour, I consumed 10 of these podcasts."</p><p><a href="https://idratherbewriting.com/blog/notebooklm-podcasts-and-technical-writing" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">idratherbewriting.com/blog/not</span><span class="invisible">ebooklm-podcasts-and-technical-writing</span></a></p>
TrendingLive feeds
Mastodon is the best way to keep up with what's happening.
Follow anyone across the fediverse and see it all in chronological order. No algorithms, ads, or clickbait in sight.
Create accountLoginDrag & drop to upload