#TechnicalWriting#APIs#APIDocumentation#SoftwareDocumentation: "Your API is nearing completion and it’s time to let the world know about it. This means that it is time to complete your API documentation effort. But, where should you start? How do you know if you covered everything that your decision makers and developers will need to select your API and get started successfully?
This article provides a checklist to help you identify the documentation you will need for launching your API. We will also include some things to consider post-launch as well to help you continue to improve your documentation."
#TechnicalWriting#APIs#APIDocumentation#AsynchronousAPIs#AsyncAPI#EventDrivenAPIs#ApacheAvro#JSON: "Luckily there's a specification similar to OpenAPI but directed at defining event-driven APIs. I'm talking about AsyncAPI. It's a specification that lets you define an API that's asynchronous in nature. By using AsyncAPI you can define, among other things, the different topics where events will be dropped, and the shape of the messages that represent each topic.
And this is where things get interesting. The shape of messages or, in other words, its payload, can adhere to specific standards. Without messages, there's no way to communicate events. And, following standards helps to guarantee the correct publishing, transport, and consumption of messages. If messages don't follow any standards, it's hard for developers to understand the shape of the messages. In addition, it's easy for consumers to stop working because, suddenly, messages are being shared in a slightly different format.
Among different message standards, there's one particularly interesting to me. Apache Avro isn't just a theoretical standard. It's also a serialization format. You can say it's a competitor to JSON but specialized in working with event-driven APIs. In the same way you can use JSON Schema to define the shape of JSON data you have Avro Schema to help you specify what Avro message payloads look like."
It all comes down to helping your API consumers integrate faster. When people decide to integrate with your API, they have a job they want to get done. They think your API could be the fastest path to solving it. But too often, building an integration with the API is as painful (or even more painful) as the original job. That’s counterproductive, to put it mildly. There are a hundred things your users would rather be doing than reading your API docs and writing basic integration code. The less you require of them, the happier they’ll be. And SDKs are the best tool for making sure your API remains unobtrusive.
The definition of an SDK is straightforward: It’s a library that surrounds your API and handles the boring parts of the integrating process, such as:
Constructing an HTTP request
Managing an authentication token
Handling retries
Parsing paginated responses
More powerful SDKs will go beyond request and response-handling basics and provide type safety and hinting in the integrated development environment (IDE). This means users don’t have to open a docs page; they’ll get all the information and feedback they need directly in their coding environment. It doesn’t get more efficient than that."
#APIs#APIDocumentation#DX#TechnicalWriting#SoftwareDocumentation: "Finding the right balance between being too simple and too sophisticated isn't easy. You might get away with a generic onboarding how-to guide if your API focuses on one single feature (as OpenCage does). Otherwise, you need to craft different onboarding experiences for each one of the consumer use cases you want to support.
One thing that works for me is learning as much as I can from consumers before writing any API documentation. Then, I focus on the top use cases potential consumers are interested in. Since those will be the top entry points for most new API users, I prepare a tutorial for each. Each tutorial offers a safe environment where developers can easily sign up to use the API. Then, by following the steps in the tutorial they will end up implementing the integration that fulfills their use case."
#APIs#APIAsAProduct#APIManagement#SoftwareDevelopment#APITesting#APIDesign#APIDocumentation: "I often make the point about API users that they fall into one of two buckets: the conceptual user (the dreamer) and the procedural user (the implementer). Breaking those two down is a blog post for another day, but essentially, this book is aimed at both, leaning more heavily toward the former.
Bruno embarked on his book-writing journey armed with a hefty dose of product thinking. He took the scenic route chatting it up with API aficionados, getting the lowdown of their challenges and triumphs. Turns out, we Product Managers are drowning daily in a sea of technical jargon without a life raft in sight.
If you’re anything like me back in the day, when I was a fresh-faced newbie diving headfirst into the API industry, you’ll relate. I’m talking fingers dancing across the keyboard like they were in some kind of turbocharged typing marathon during every single sit-down with architects, developers, and engineers. Seriously, the clickety clack of the keystrokes echoed as my own personal symphony: Reverie of Desperate Recall.
Why does that happen? Design and implementation costs evaporate as soon as an API is "finished" and consumers are using it. After that, the only thing that still matters to consumers is that the API behaves as it should. If not, they'll look for ways to fix the challenges they're having, and that's where support comes in.
Unless consumers can get all the information they need from the API documentation. If the API documentation can be the preferred method consumers use to troubleshoot their integrations, then you'll end up spending less on support. There will be less hand-holding required as consumers can fix their issues by themselves." https://apichangelog.substack.com/p/two-ways-to-influence-business-growth
Make API documentation comments easier to write and easier to read in source form by introducing the ability to use Markdown syntax in documentation comments, alongside HTML elements and JavaDoc tags.
Do not adversely affect the interpretation of existing documentation comments.
Extend the Compiler Tree API to enable other tools that analyze documentation comments to handle Markdown content in those comments.
Non-Goals:
It is not a goal to enable automated conversion of existing documentation comments to Markdown syntax."
#APIs#APIDocumentation#Marketing#SoftwareDocumentation#TechnicalWriting: "So, it looks like API documentation is a form of marketing. It's not traditional marketing but more like one directed at a very specific technical audience. An audience that knows what they want and is very knowledgeable about certain technologies.
The goal of documentation is to help a target audience engage with the API as quickly and easily as possible. By aligning the needs of consumers—using their preferred programming languages and offering SDKs—with the business objectives, documentation is a marketing tool you can use to drive results."
Learn all about Redocly the handy OpenAPI documentation tool with a Swiss army CLI that does everything (even linting!), and a bit more about the plan for OpenAPI v4 (a.k.a Moonwalk).
Good natter in general with @lornajane who I always love catching up with.
#APIs#APIDocumentation#Tutorials#TechnicalWriting#SoftwareDocumentation#SoftwareDevelpment: "The best tutorials present information that helps consumers fulfill a use-case scenario that feels real and meaningful. Instead of coming up with a made-up use-case, you can research what are the things your API consumers would want to do. Then, create tutorials that teach how to achieve those results with your API. The goal of the tutorial is to educate readers on how they can use your API—or some of its operations—to get their job done.
So, what are the elements that a good API tutorial should have? Let's look at some of the most important ones:"
#SoftwareDocumentation#DocsAsTests#DocsAsCode#APIDocumentation#TechnicalWriting#SoftwareTesting#SoftwareDevelopment: "I initially developed and implemented Docs as Tests at Skyflow, a startup that moves fast and releases features and updates even faster than I’d experienced before. I searched for tools to help me manage the pace of changes: there were style linters, API testers, and engineering-focused testing tools, but there wasn’t anything to easily help me validate the product descriptions or procedures in my docs. So I built my own, and Doc Detective was born. Doc Detective is a toolkit that parses docs and runs tests (like stepping through procedures) directly against UIs and APIs. It’s designed so non-engineers can use it individually, but teams can also collaborate. When I set it up to test my docs, it caught issues that I had no idea of. It was a game-changer.
But Doc Detective is just a tool (a good one, I like to think!), and no tool solves every problem. I wanted to find a way to apply my learnings to the broader docs community, and I came up with Docs as Tests—a strategy that can be implemented with whichever tools you choose to validate your docs. I’m excited to share my learnings with you and to learn from you as well."
The specifics may vary from team to team and tool to tool, but this is the broad shape of what this process looks like:
Write docs examples in unit test suites
Excerpt example code for inclusion in docs
Include example code in docs
Run docs tests in CI
In another post, I’ll dive deeper on what your docs code examples and tests should cover. For this topic, I’ll follow a code example from the unit test suite to publishing the docs."
#TechnicalWriting#APIs#APIDocumentation#SoftwareDocumentation: "In this podcast, I chat with Bob Watson about an upcoming API documentation course he'll be teaching at the University of Washington. Bob has extensive experience working as an API technical writer at big tech companies like Microsoft, Amazon, and Google. The UW reached out to Bob to develop this new course offering. The 14-week evening course will cover fundamentals like understanding developer behaviors, working with various types of APIs, publishing workflows, as well as hands-on practice. A key component is having students create API documentation portfolios they can use to demonstrate their skills."
Everyone is looking to me for API doc best practices and process. Validating, but also a little intimidating, like the teacher learning the content the night before to stay ahead of the API doc class while teaching seven other classes at the same time.
I'd appreciate y'all sharing any thoughts & references & resources, from theory to implementation.
#API#APIs#APIDocumentation#TechnicalWriting: "By now, the value of good API documentation should be clear. Without good documentation, users find it hard to interact with your API and even to start using it, to begin with. There are many ways to go about when it comes to creating good API documentation. The five elements you just read about will increase the quality of your API by reducing the friction users have when interacting with it.
A combination of customized "getting started" how-tos with a set of tutorials written to align to specific use cases is an excellent starting point. If you add to these a full API reference, code samples, and an up-to-date changelog, then you have a winning combination."
This means that in the JetBrains State of Developer Ecosystem 2023, 90% of those who write documentation don’t call themselves technical writers, which raises questions about collaboration between teams, documentation quality and consistency, and the role of technical writers."
Longer articles facilitate page search, something developers are used to using in one-page API reference sites, reducing the chance of navigation issues. Longer pages allow readers to follow a logical flow and grasp the complete concept. With effective headings and subheadings, it’s easy to locate specific sections without extensive jumping between pages.
There’s nothing wrong with fragmentation per se; it’s just good practice to be conscious of how you split related topics to ensure it is clear how they are connected and avoid fragmentation if it is not necessary.” https://docsgeek.io/blog/posts/task-based-api-docs
API documentation includes detailed information about an API's available endpoints, methods, resources, authentication protocols, parameters, and headers, as well as examples of common requests and responses. Effective API documentation improves the developer experience for private, partner, and public APIs, but it also offers distinct benefits for each API type. For instance, private API documentation improves cross-team collaboration, while public API documentation makes it easier for leaders to understand a third-party API's intended use case and determine whether it will help advance their organization's business goals. Teams that prioritize API documentation typically see higher rates of API adoption, fewer support tickets, and—in the case of public APIs—increased revenue.
Here, we'll start by discussing the role that API documentation plays in an API-first world. Then, we'll review the key components of API documentation, as well as some API documentation best practices. Finally, we'll explore how the Postman API Platform enables producers to create API documentation that sets their consumers up for success."
#DX#DeveloperPortals#APIs#APIDocumentation#InformationArchitecture#TechnicalWriting: "An out-of-the-box developer portal can speed up your go-to-market. But after a quick launch, a developer portal that cannot be customized can become a roadblock to the long-term success of your API program. As the API portfolio grows and matures, your strategy will probably change and require more specific business experiences. In this case, a preset solution may no longer suit all the desired goals, and retooling might become necessary.
The Codat Docs team went through such a journey: they wanted to have more flexibility and control over their docs, and they built their own custom solution. Now, their documentation site is more resilient. With the help of the new landscape, large-scale changes can be managed on over three hundred pages of content without interrupting the existing user experience.
To mention another example, the Monite API Developer Portal uses a robust content management system that is exclusively tailored for developer documentation. The comprehensive resource was designed to provide an end-to-end self-service experience to developers.
The ability to extend and customize your developer portal plays a crucial role in executing on the API business strategy."
#API#APIDocumentation#APIProductManagement#ProductManagement: "An engineering team member can perform a limited form of product management on a microservice. However, in all but the most minor or most trivial cases, the product management work requires a dedicated professional.
However, the rub is that not all product managers are created equal. When companies embark on an API transformation, they may reassign whatever product managers they already have employed. Or they post job hiring using whatever product management boilerplate lies within their HR systems, not thinking to customize for specific technical considerations. "They can learn the API bit on the job," the thinking goes, "others will do the technical stuff".
There are product virtuosos equally adept at creating great mobile apps, internal platforms, desktop experiences, or APIs. And there are many similarities between software product management and API product management. Several key differences also exist due to the nature of the products and the customers they serve. Individuals who can "do it all" equally effectively are few and far between.
These following subtle but significant differences can trip up otherwise competent product managers."
#AI#GenerativeAI#Programming#Coding#ChatBots#SoftwareDevelopment#TechnicalWriting#APIDocumentation: "As if documenting code for one project weren’t enough, API technical writers must also support multiple projects simultaneously, often with different types of code. You might document a Java API for one project, a REST API for another project, some Go code for an SDK, some C++ code for another project, and so on. It can be nearly impossible to be fluent in all of these languages. Even keeping the terminology straight (a “function” in one language, a “class” is another, etc.) can be challenging.
Fortunately, you can use AI tools to learn code. AI tools can act like a friendly programming buddy who is sitting next to you, ready to explain anything you want, at whatever technical level you need. You can zero in on a specific question or broaden it out to increase your understanding from ground zero."
#AI#TechnicalWriting#SoftwareDocumentation#APIdocumentation#ShellScripting: "AI tools empower technical writers with scripting capabilities, whether it be shell scripts, Python scripts, CLIs available at your work, or more. In particular, shell scripting can help you automate parts of your build process that are tedious, making it easier to push docs through advanced build and publish processes. In a world of doc ops, where continuous builds and publishing are becoming the norm, tech writers need as much automation as possible with these processes."