"How to leverage documentation effectively in Cursor through prompting, external sources, and internal context
​
Why documentation matters

Documentation provides current, accurate context. Without it, models use outdated or incomplete training data. Documentation helps models understand things like:

- Current APIs and parameters
- Best practices
- Organization conventions
- Domain terminology

And much more. Read on to learn how to use documentation right in Cursor without having to context switch."

https://docs.cursor.com/guides/advanced/working-with-documentation

#AI #GenerativeAI #Cursor #TechnicalWriting #Documentation #SoftwareDevelopment #APIDocumentation #SoftwareDocumentation

🚀 New Release: API-Doc-Crafter just got sharper. Cleaner. Meaner.
Giving my little OpenAPI merging monster some upgrades.

It all started with a simple idea: merge OpenAPI specs from multiple repos.
Now? It transforms outdated Swagger specs to OpenAPI 3+, generates HTML pages with full navigation, and allows customization via config or env.

✨ SecurityRequirement deduplication - because why merge APIs if you can't also merge logic?

🧠 Custom metadata enrichment - inject your info, license, contact, and docs straight from config. No more excuses.

🔁 Better parser fallback - now tries more ways to read broken specs than your average intern in panic mode.

🎭 Variable substitution in outputs - ${variables} be gone. Use env or config, stay DRY, stay sane.

🧪 Tests expanded. HTML, JSON, YAML outputs covered like a nuclear bunker.

🧰 Powered by GraalVM, no reflection, blazing fast.
🐳 Native Docker builds.
🧼 Reflection config surgically trimmed. Less bloat. More edge.

Project: https://github.com/YunaBraska/api-doc-crafter
Happy crafting. And remember: if your docs aren't automated, they're probably lies.

#OpenAPI #Swagger #APIdocumentation #DevTools #GraalVM #Java21 #Docker #Automation #CleanCode #DevLife #APIDocs #OpenSource #DeveloperTools #coding #programming

"Let me be blunt.

If your startup offers APIs and you don’t have a portal, you’re lighting developer acquisition money on fire. 💵 🧯🚒

Here’s what a good portal actually does:

Shortens time-to-value: faster POCs, faster adoption.

Reduces support tickets: devs can find what they need.

Builds trust: your API feels stable, documented, and ready.

Increases conversion: when docs show how easy it is to integrate, not just tell.

Still sending PDF onboarding packets to partners?

C’mon, boo. 🥲"

https://www.quetzalliwrites.com/newsletters/developer-portals-dev-friendly-or-dev-frustrating

#DevPortals #DeveloperPortals #APIs #API #APIDocumentation #TechnicalWriter #TechnicalCommunication

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

Here is some more context to help you decide on an approach and get started."

https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299

#API #APIs #APIDesign #REST #APIDocumentation #OpenAPI #DocsAsCode #TechnicalWriting #TechnicalCommunication

Rapid URL Indexer has published comprehensive documentation for our indexing API! The guide covers all endpoints including project management, status checking, report downloads, and credit balance monitoring. Authentication uses API keys with X-API-Key headers, and we've included detailed error codes and rate limiting info. Check out our OpenAPI 3.1 specification for easy integration. #RapidURLIndexer #APIDocumentation https://rapidurlindexer.com/indexing-api/

Do developers need code samples in API documentation?

https://idratherbewriting.com/blog/code-samples-might-not-be-needed-anymore

#APIDocumentation #TechWriting #CodeSamples #AI #DeveloperTools #SoftwareDocumentation #APIs #AIInTechWriting #DevDocs #TechnicalWriting #APIDocs #Coding #AIvsManual #SoftwareDevelopment

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

The reason this isn’t caught is simple: We’re not expecting it.

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.

The reason this happens is because of an intentional behavior on the server. This behavior is called Lenient Handling or Strict Handling."

https://robertdelwood.medium.com/understanding-query-parameter-handling-in-rest-calls-1821e0c3fa8c

#APIs #RESTAPIs #Rest #APITesting #APIDesign #APIDocumentation #SoftwareDevelopment

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

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?”).

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

If we focused more on these sophisticated tasks (beyond click-button AI), I think tech writers could have a brighter future.”

https://idratherbewriting.com/blog/recursive-self-improvement-complex-tasks

#TechnicalWriting #SoftwareDocumentation #APIDocumentation #AI #GenerativeAI #LLMs #Docs

“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.”

#APIs #APIDocumentation #Markdown #TechnicalWriting #Git #DocsAsCode

https://apichangelog.substack.com/p/three-elements-of-a-good-api-readme

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

https://www.apimatic.io/blog/how-to-design-a-quick-start-guide-for-your-api

#TechnicalWriting #APIs #APIDocumentation #SoftwareDocumentation #GettingStarted #Tutorials #SoftwareDevelopment #DE #DeveloperExperience

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

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.

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

https://apichangelog.substack.com/p/producer-oriented-api-documentation

#TechnicalWriting #APIs #APIDocumentation #SoftwareDocumentation #APIMetrics #APIAnalytics #SoftwareDevelopment

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

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

https://idratherbewriting.com/blog/trends-predictions-2025-tech-comm

#AI #GenerativeAI #TechnicalWriting #TechnicalCommunication #APIs #APIDocumentation #PromptEngineering #TechComm

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

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.

There is information to be mined from bad job descriptions, if you know what to look for and know how to use that information."

https://robertdelwood.medium.com/reading-api-documentation-writers-job-descriptions-92124e5d9008

#TechnicalWriting #APIDocumentation #APIs #SoftwareDocumentation #SoftwareDevelopment

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

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

https://robertdelwood.medium.com/the-truth-about-describing-strings-932c28bbde22

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

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

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

https://bump.sh/blog/how-spec-first-api-documentation-aids-partner-integration

#APIs #APIDocumentation #TechnicalWriting #SpecFirst #SoftwareDocumentation #Docs #DeveloperExperience #DocsAsCode

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

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.

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.

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

https://robertdelwood.medium.com/why-i-dont-like-try-it-f44112ed1b6d

#APIs #APIDocumentation #SoftwareDevelopment #TechnicalWriting

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

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.

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

https://nordicapis.com/understanding-the-root-causes-of-api-drift/

#APIs #APIDesign #APIDocumentation #APIDrift #SoftwareDevelopment #Programming #TechnicalWriting #OpenAPI #Swagger

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

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

https://idratherbewriting.com/ai/prompt-engineering-iterative-chain-of-thought.html

#AI #GenerativeAI #PromptEngineering #LLMs #Chatbots #TechnicalWriting #SoftwareDocumentation #APIDocumentation #SoftwareDevelopment

#APIDesign #APIs #APIGovernance #APIDocumentation #DX #DeveloperExperience: "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.

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.

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

https://www.infoworld.com/article/3529600/how-do-you-govern-a-sprawling-disparate-api-portfolio.html

🚀 Struggling with fragmented API documentation across multiple products?

Want to improve your developer experience and reduce support requests?

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

In this presentation, I cover:

✅ Auditing existing documentation for consistency.

✅ Creating a unified style guide and using automated tools.

✅ Building a centralized documentation portal.

✅ Collaborating with diverse stakeholders for a cohesive strategy.

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!

If you have any questions, doubts, suggestions, or feedback, feel free to leave a comment.

#APIDocumentation #DeveloperExperience #TechnicalWriting #ProductManagement #APIs #DX #DeveloperExperience #TechDocs #SoftwareDocumentation

https://drive.google.com/file/d/1CyPzuUrz5S8uEIkj2YfXMts_41kQBOHM/view?usp=drive_link