![]() ![]() You want to share best practices for your specific technical area. Create an API explorer or include the functionality in your API reference.Īnd not just speak their programming language. It’s one thing to see what’s possible in a reference-it’s even better to experience it. ![]() Many companies use an OpenAPI tool like Stoplight (an EveryDeveloper client) to maintain a source of truth from which to generate API references. When changes to the API are published into the OpenAPI document, SendGrid automatically runs scripts to generate correct user-facing reference documentation for its API. SendGrid’s API reference (above) has a machine-readable version of its OpenAPI document in a GitHub repo. Whenever any API is updated, those changes should automatically be available in an updated reference. For documentation, you can use OpenAPI to generate references. These JSON or YAML documents are intended to be machine-readable and can be used in many ways. The OpenAPI Initiative has created an industry-driven format to define an API’s elements. Increasingly, API references are built from OpenAPI documents or other API descriptions. Best of all, SDKs typically simplify authentication, often the hardest part of getting started with an API. By installing with a package manager or downloading the library, a developer can skip preparing the API calls with appropriate headers and other details. But there’s no quicker way to get up to speed than providing an SDK in the developer’s preferred language. Provide Language-Specific ContentĪny modern programming language should be able to make HTTP requests. In particular, Twilio has use case tutorials within its docs, so these solutions can be discovered and described from a developer point of view. The company backs up these use cases with solid documentation that would fit well in other sections of this post. The latest iteration (shown above) uses a more enterprise term, solutions, but eases naturally from high-level discussion to code-packed tutorials. Twilio has always done a great job of inspiring with use cases, something all audiences appreciate. Twilio is attempting to hit a wide audience with its current messaging, but its developer roots remain. You’ve already told them what’s possible, so here you need to show them. This meets a developer at a basic level of knowledge and holds their hand to a quick win. ![]() The most important API documentation you can provide is a quickstart or getting started guide. Between these two pages, developers can figure out in a hurry (and without even signing up) whether they’ll be able to solve their problem with Plaid. On the developer homepage, you can quickly see more about what’s possible: transactions, income, balance, and more is available with Plaid. Since the API is core to everything the company does, you can also find docs in the global navigation. ![]() Keep in mind that this is the homepage for the whole company. In one sentence, developers know they can use Plaid to connect to their users’ bank accounts. Plaid could have easily written something hand-wavy on its homepage like “the future of financial services.” In fact, that line shows up further down the page, but in the context of five common use cases. Then, ensure you clearly communicate the main benefits of your API or platform. Make it easy to find your portal or developer homepage. Show Developers What’s PossibleĪ developer wants to quickly answer whether your solution will solve their problem. Based on great examples of each, you can implement some of these ideas today. This post will cover these common areas of documentation, plus some areas you might not typically see called docs. While nobody makes bad documentation on purpose, everybody can help make it better.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |