Today we’ve got a special guest on the blog — Ceci Stallsmith! If you were at API Mixtape 2023, you got to see her in action as a speaker. If you missed her talk, you’re in luck, because today’s post is covering the same topic: how to create developer marketing that doesn’t suck. 

Take it away, Ceci: 

This post explores specific ways to make your developer marketing notably not bad — maybe even good! Read on to learn about what to do (and what to avoid) to hit the mark with your developer audience. 

Things to avoid: the bad 

Bad 1: Tone-deaf content

💫 Join the movement, create customer magic, drive success, better-together, instant innovation, unleash the power, the platform of platforms. 💫

Phrases like these are why people say that “developers hate marketing.” Tone deaf copy is, in my opinion, the greatest offender in the world of bad dev marketing. 

You can always tell when marketing content was written and built by someone who doesn’t think about, talk to, or understand what motivates developers.

Example 1:

If you show this hiring plea to most developers, especially “good” ones, it feels overly try-hard. It looks developer-y, it’s code! But it repels. You could say this is “code-washed” — the marketer thinks they’re speaking the developer’s language, but their assumption is in error.

Example 2:

Companies often hire B2B marketers with track records of successfully marketing to enterprise buyers. Sometimes these marketers use phrases like “strategic alignment” and “drive success” and “join the movement” and “create customer magic.”

Those aren’t inherently bad words.

They are actually great words for enterprise software buyers. In fact, I took most of them from the Salesforce homepage! But these aren’t words you hear from most developers. If you need to market to both enterprise buyers and developers, consider having different “venues” for doing so (a separate blog, a community of developer users, etc.), along with creating different style guides for each audience. 

Example 3:

Companies hire a big-budget, brand-heavy marketing agency, who then comes up with things that look and smell “developer-y.” They probably put brackets <> or slashes // in front of the logo or on pages developers will see. Again, they aren't actually talking to developers, they’re just doing things that feel “developer-y” to them. It’s like adding Helvetica to a page on your site to appeal to designers — because designers like Helvetica, right? 

Developers come in many flavors

One more note before I turn the tables: there are many, many types of developers. “Developers” aren’t one, single audience. There are frontend developers, backend developers, data engineers, and DevOps, to name a few. Even within those buckets, developers have varying language preferences, levels of seniority, and expertise. “Developers,” without any qualifications, is not a valid audience. If you’re targeting developers, dial in an understanding of what types of developers you’re working with. 

Good developer marketing copy is concise, uses language that your target audience uses, and focuses on their actual pain points. Good developer marketing is done by people who work with, get feedback from, and understand developers. 

I wish I could share some cringe examples out in the wild…but that would be too cruel. Let’s look at good examples instead:

AWS: I have a lot of respect for AWS's product marketing. They aren’t as cute as some companies in the dev space, but they are gloriously straightforward. The copy cuts right to the value, with no jargon. Knowing their user, they are not afraid to expect their audience to do some reading. If you’re feeling lost, copy AWS’s style and you’ll instantly be in better shape. 

Vercel: Vercel’s homepage is another example of great audience awareness and quality product marketing. Unlike AWS, they bring a bit of personality to the table. The copy doesn’t get lost in personality, though — it tells us right away (1) who the product is for and (2) what it can do for me. Again, no jargon that makes my eyes glaze over.  

Now - let’s look at the two examples together through the lens of understanding your audience. AWS and Vercel are trying to attract different types of developers. Vercel’s homepage is super smooth and focuses on getting straight into the action. They’re nicely packaged up and make me feel like I could use their product, even without being an expert. 

If AWS used Vercel’s homepage vibe, it would frustrate users. Vercel is targeting individuals who want to bypass the hassle of setup. Their focus is on developers of varying skill and experience levels, who are looking for a solution that internal stakeholders can use without it being too technical to access. AWS, on the other hand, is not trying to position itself for beginners. Their content is deeper, more descriptive, and more heavily technical — right off the bat.

Bad 2: Do nothing

Developers hate marketing, so let’s just not do it. 

Actually, a number of very successful developer companies have taken this approach.

There are companies that “do” this and succeed, so I want to be careful on this point. Here’s my thesis: even if your company doesn’t have a marketing team, you are doing marketing. Marketing is how you show up to the world, the way you talk to the industry and users, and the way your product gets discovered. You don’t need a card carrying marketer in order to “do” marketing. 

But, if you don’t have anyone who: 

1. Carries the brand or cares about how the company looks and feels to outsiders
2. Can effectively position the product (explain what it does and why use it on a website, blog, etc.)
3. Can help the company win more developers over 

Then it’s time to figure out how to do developer marketing. This can mean hiring DevX, or “growth!” or actual marketing, I don’t care what you call it.

Worst case here: 

1. If you build it, they usually won’t just come (unless you built OpenAI or a product with ridiculously good product-market fit) 
2. You look messy and inconsistent externally, which doesn’t engender trust
3. Some developers can use your product, but a lot of them either never hear of it or, if they do, they find it confusing or unappealing and move on quickly

So, consider your company. Who might be doing “developer marketing” without the official role? How can you enable them to do it more? If you do hire a marketer, but feel that you’ve been doing a decent job with your developer brand, make sure that the new marketer sits down with each of your shadow marketers to understand the look, feel, and language of your “developer brand.” Some of the best marketers I’ve met don’t have marketing titles. They’re DevRel, widely read CEOs, devs or PMs on Twitter/X, and developers who frequent and write on HN. 

Bad 3: Try to out-market a weak product

This can work in enterprise and consumer land — you can out-market a weak product in the short run. Influencers can push thousands of units of products before consumers realize that they’re wasting money. Sales teams can close annual subscriptions that might not renew.

But with developer products…you can’t do the same thing. The user (developer) is too intimate with your product and too picky to deal with junk. If the product isn’t there, fix that first. This sounds obvious, but sadly isn’t at many companies. 

One big exception: if you’re building an ecosystem, you can have a bad platform API and acquire developers if you are winning them users. This can be abided. But you can’t have a weak developer tool and expect marketing to solve that problem. 

So, don’t:

• Over promise
• Avoid investing in documentation or DevX 
• Try to be super cute without delivering value

Bad 4: Forget about the other audiences

Developers don’t build in a vacuum. Product managers, security teams, procurement, legal, etc. are all part of the process — don’t forget them. They can be surprising champions! Beware of alienating these audiences. Give them on-ramps with your product, even a landing page or friendly blog post that helps them understand why they should want to hang out with you. Giving a non-dev audience the chance to look cool championing your product is a win. 

Developers tend to consume developer products, but other stakeholders do access them and block or approve their use. A couple of examples of companies that have kept secondary audiences in mind:

• When it comes to Twilio, developers care about the API for sending texts, but a product manager is worrying about deliverability and ability to send to WhatsApp — both audiences need to be won over.
• Figma (I know, designer product, but hang with me) has done an excellent job with extending to non-design audiences. The core product is readily accessible to non-designers (unlike many other design tools), so the non-core user still has a great experience in Figma. And FigJam is their product for everyone, bringing periphery or secondary users in as newly minted product champions.

So, what’s good? 

Good 1: Show, don’t tell

The consummate thing to learn about developer marketing is "show, don’t tell." Developers want to build and they’re a sophisticated audience. Your goal is to unblock them with marketing, and literally showing the product in action is one of the best ways to do that. 

Show the code snippet. Show the product doing something. Help the developer “get it” and they will get started.

Example 1: Retool. ReTool’s homepage shows the drag and drop power of their product in action, front and center. The video is even partially above the fold, so users barely have to scroll to see the mini-demo.

Example 2: WorkOS showcases their APIs and language support:

Example 3: Astral. Maybe my favorite example, here’s a screenshot from the Astral homepage. They’re demonstrating just how fast RUFF (a Python linter) runs with a literal speed test — excellent showing.

Good 2: Your marketing site matters, but your docs REALLY matter

Say what you want, Stripe has built the most iconic developer brand of the last decade. What made them so amazing? My take: docs.

Great docs:

1. Are clear and well written, well ordered, and have good information architecture. It is really easy to end up with hairy, messy docs that are too long and hard to parse, or don’t explain enough. Invest here. 
2. Have excellent samples to pull from quickly. Again, unblock your audience. If they want to try it out, make it easy for them. Add links to a product like Codesandbox or Replit to let people try the product out right away.   
3. I defer to ReadMe’s guidance on building great docs. They do it for tons of companies and Greg is one of the most thoughtful DX people in the business. 

Good 3: Be succinct

This is the opposite of the first “bad,” which is to be tone-deaf, and is also part of what makes for good docs, but it needs to be repeated. Be ruthless about marketing copy. Eliminate jargon and business lingo. Speak plainly. Be technical. Speak like your audience.

How can you do this?

1. Conduct user interviews. It’s so basic, but if you have developers who use your product, then interview them, understand them, and literally record their words. Make sure your copy matches their tone (as a group). So many companies don’t talk to users. Don’t be that company!
2. Use the Hemingway tool to trim your writing down. Or try an AI writing tool. There are a lot of them right now. Somehow I didn’t use one to write this post and feel like that was a little dumb. 
3. Run content by your dev team. If they cringe, edit. 

Good 4: High-value content marketing

Fluffy content marketing like listicles are not going to pay off for your team. Do content marketing like Fly.io, Honeycomb, or Earthly.dev.

What makes it good?

They’re serving up steaks. Their writing is technical and they understand what they are talking about. There aren’t paragraphs of fluff to wade through in order to get something of value. It’s harder to write technical content with depth, but will drive your content engine: fueling impressions, SEO boost, and overall growth of your audience. Writing puff pieces to try and fill a content calendar won’t get you anywhere.

Fly.io has great content. These articles are specific and they explain how to solve a real problem. Best of all, they are not written for SEO bots, but for real humans. Here’s a great example — this is a 25 minute read, but with a lot of real, valuable information. Yes, SEO will pick it up because there are keywords in it, but that post is written for a human to consume.

Good 5: Provide a variety of on ramps 

Provide everything from drag and drop or copy/paste integration options to totally raw endpoints. Why? Developer use cases vary. 

Stripe is, again, a great example here. They have options and instructions for everything from adding payments with no code to building the full, robust, customized integration with their APIs. You might be surprised to find that often the people using the no or low-code options for your product are actually highly technical developers! Your product is often a small step in a bigger project, and making it really easy to integrate with or build on can help them move on to other technical challenges. 

Your audience may also have different levels of skill and/or desire to build with your product. Be ready for both! Provide:

• Samples of varying level
• Quick starts
• Copy paste options 

See Stripe’s many levels of getting started:

And Plaid’s quick-start guides:

Let’s conclude

I hope this guide is helpful! What else would you add to the list? Any further sins or virtues of developer marketing that you consider?

Send us your examples of excellent developer marketing — whether you’ve built them as a team, or you’re admiring them from afar! We want to showcase more companies succeeding at this work. Don’t be a stranger: ceci@calyx.consulting.

Ceci runs Calyx Consulting with her business partner Paige, where they help companies ranging from Stripe, Airtable, and Zoom to earlier stage startups, like Replit and Render, with developer go-to-market. She is currently the fractional CMO at Prefect, a data orchestration platform. Previously she built and ran platform marketing at Slack, invested in developer tools at Bessemer Venture Partners, and helped build the platform at Box as a DevRel. 

Thank you, Ceci! 

If you want to learn more about Ceci, you can check out this post in its original home, browse the rest of the Calyx Consulting Substack, check out the Calyx Consulting site, or follow Ceci on X. 

Happy Groundhog Day! While you’re waiting to find out if we have six more weeks of winter, why don’t you take a look at our news and updates from January? We’ve got new features, improvements, and even some events on the horizon. Read on to see what our team got up to last month, find out how to make the most of those updates, and where to catch us live (virtually and in person): 

More Nested Levels 🪺

Looking for more flexibility and options in how you structure your Guides and API Reference? We’ve got good news for you: we’ve introduced an additional level of nesting! That makes for a total of three levels of pages per category. Now, any parent page can have subpages and those subpages can have nested (second-level) subpages. You can read more here and see it for yourself by checking the Guides or API Reference sidebar in your dashboard. 

Webhooks 🪝

Another popular request has been support for OpenAPI webhooks, so we’re thrilled to announce that webhooks support is officially live in our API Reference! This means that now, if you sync an API definition with us that contains webhook definitions, ReadMe will render those definitions as pages that look like the API Reference pages you know and love (rather than ignoring your webhook definitions, which is what happened previously). Right now, we support OpenAPI through v3.1.0 — you can keep an eye on our evolving support for the OpenAPI Specification at our OpenAPI Compatibility Chart. And if you want to try it out, you can use this example webhooks definition. 

ReadMe Labs 🧪

Want to enable experimental features and be among the first ReadMe users to try them? We’ve added ReadMe Labs to the project dashboard, which lets you test experimental features, starting with GraphQL. You can find it under the “Admin” section of the “Configuration” settings panel — you might also notice that we’ve reorganized that sidebar to make it easier to find the settings you’re looking for. 

Reusable Content ♻️

We launched Reusable Content in December, and we’ve been thrilled with the feedback so far! We have, of course, continued to perfect it — updates this month included adding a link to manage Reusable Content from within the editor and adding support for renaming Reusable Content blocks. If you want to learn more about Reusable Content and how to set it up, head to the docs to get started. 

API Reference, Guides, and Docs 📚

We rolled out lots of updates across these three areas in January:

• We’ve added improvements in how the API Reference handles null values in enums from your OpenAPI file
• The API Reference response schema examples now expand by default instead of being nested in a modal (you can change this in your configuration, if you prefer the previous setting)
• In your Docs, the deprecated banner now spans the full width of the page
• We’ve refactored the mobile page navigation in Guides and Reference to support more interactions and additional levels of nesting
• We’ve improved the consistency in navigation between the Guides and the Reference sections
• In your Guides and API References, there’s now an automatic redirect after the slug is changed on nested pages

Other ReadMe changes and updates 🪄

• All plans can now choose between setting Dark/Light/Auto as the default theme
• Search results now include the contents of your HTML tables
• Various improvements to table views in Developer Dashboard 
• Our Slack integration now notifies you when an anonymous user makes suggested edits
• Updated and improved sidebar performance in the Editor for users with a large amount of categories and/or pages

Meetups & events 🍻

If you’ll be going to Developer Week later this month, come say hi. Our CEO, Greg, will be discussing how to improve your DX (without having to overhaul your API) on Friday at 10 AM PST. Can’t make the event in person? That’s fine — you can also join for the virtual version on the 29th, also at 10AM PST. We hope to see you there!

In other event news, we had our company holiday party and it was, as usual, a blast, complete with a skating rink visit and a skiing-themed photo booth. We’re already looking forward to next year! 

That’s all for this round. If you want more details on the product updates and improvements, head to the ReadMe changelog to get the scoop and stay up to date as changes are announced. We’ll keep you posted on any upcoming events or other news, but in the meantime, if you have any questions, feel free to reach out to our team. Stay warm, and enjoy your February!

Ever tried to put together a complex piece of furniture without the instructions? We all know that’s typically a recipe for disaster. But that’s exactly what some companies expect developers to do, when they have API documentation that’s hard to find, poorly maintained, or difficult to understand…or worse yet, don’t have any API documentation at all 😱

As Ruben Vermeersch said, “Your APIs are only as good as the documentation that comes with them. Invest time in getting docs right.” If you want developers to successfully use your API and enjoy the experience of using it (and you do, or the API wouldn’t exist in the first place), your documentation needs to get them to first call as fast as possible. 

Whether you’re learning the ropes for the first time, looking for a refresher course, or want to improve your existing API documentation, we’ll walk you through what exactly API documentation is, why writing good docs matters, and share our best practices and tips for writing it along the way. Let’s get started 💪

What is API documentation? 📖

For most developers, API docs are a means to an end. Devs want all the details about how to use your API and successfully integrate it into their application of choice. At the same time, they’re often busy people who don’t have the time or attention span to sort through disorganized or unclear information. This means you have to be strategic about how you present your API information. 

Think about your API docs like a reference manual: 

• A table of contents and clear hierarchy of information indicates where to find important information
• Topics are first outlined at a high level
• Sub-topics have more details and examples to hit your points home 

End users should be able to get the gist of things by skimming your docs, but they should also have the option to dive deeper into the details if and when issues come up.

In the past, conversations around APIs have mostly been focused on usability and reliability issues — poor design, uptime, latency, etc. These are, of course, critically important; it doesn’t matter how good your API documentation is if the API itself is badly designed or unreliable. Conversely, though, even the best API imaginable will be painful to use without documentation that’s comprehensive and easy to navigate, ideally with code samples and an interactive playground to give new users a quick way to get started. 

Why document APIs? 🤔

Especially if you’re approaching API documentation from a non-technical background, you might wonder why it’s so important. After all, developers are…developers, right? They can pick things up quickly, so surely it doesn’t matter if you don’t have the best docs in the world, as long as they’re acceptable. However, as usual, that’s not the full picture. 

Not only are developers a complex and diverse group of individuals, but they are often the decision makers when it comes to API adoption, and/or critical stakeholders in the integration process. Documentation should always be optimized for developer experience. Good developer experience helps to decrease onboarding time, increase user satisfaction, and improve adoption rates.

It’s also worth noting that API-led or API-first companies are becoming more and more mainstream. If your docs are clearer and easier to use than others in your industry, you have a better chance of becoming the first choice for whatever use case your API serves.

Finally, good documentation saves your team money and effort in the long run. Comprehensive references can decrease the amount of support tickets and time spent training new users. One example is ReadMe customer DriveWealth, who found that a manual process for updating documentation created more support tickets, as customers would occasionally see outdated information before the team could finish updating it. 

How does API documentation impact developer experience? 🧑‍💻

Your goal is for your API documentation to establish a great developer experience. On the most basic level, your documentation should be clear and thorough, accurate and up-to-date, and simple enough for someone without any prior API experience to use. 

That’s the bare minimum, though. Ideally, a documentation hub will differentiate between how-to guides and API references, contain code snippets with step-by-step tutorials built around those snippets, and include an interactive playground to help developers start using the information right away. If you really want to go the extra mile, you can add community elements so developers can interact with other users (and your team) to get the information they need. 

These small things add up when it comes to API adoption. Remember: if your API docs offer a subpar developer experience, your end users might just choose a competitor API instead.

Want to learn more about developer experience? Start here: 

• Why DX Matters: Driving API Success with a User-First Approach
• Guide to Developer Experience
• Webinar Recap 🎤 Developer Experience, API Performance, and More with AWS (with our very own CEO!)
• Hubs We Love ❤️ Little Details With a Big DX Impact

How to get started documenting your API ✍️

Writing API documentation can seem daunting — there’s just so much information to distill. That’s why many in the API space rely on tools like OpenAPI as a starting point. OpenAPI offers a powerful ecosystem of tools to get comprehensive API documentation up and running quickly, so users can update their docs as the API evolves.

Whether you opt for OpenAPI or decide to document your API manually, follow these four steps to get going:

1. Know your audience. Everyone knows that API docs are primarily for developers. But not all developers have the same level of experience, and it’s becoming increasingly common for people in other roles to also interact with APIs in their day-to-day work. As a best practice, aim to publish documentation that can be used by people of all skill levels.
2. Understand the API adoption journey. Put yourself in the shoes of a developer who’s never come across your product before. What are the use cases they’re solving for? What other ways might they use your API in the future? Keep asking yourself this series of questions and map out the user journey, step-by-step. This can help you create an outline and structure for your documentation.
3. Edit and edit again. No documentation is perfect at the outset. It goes without saying that you should use spell check and aim to keep sentences and paragraphs short. You can also read your docs out loud — any confusing spots or unnecessarily long sentences will become much more obvious. Do they make sense? Is there any missing context or information? 
4. Structure for skimmability. Even if the content itself is good, it will probably get skipped over if it’s all one massive block of text without any clear hierarchy of information. Aim to create short paragraphs, bold important information, use numbered and/or bulleted lists when it makes sense, and have clear headers and subheaders to break up the text. 
5. Peer review. Despite your editing efforts, there are bound to be mistakes you don’t find. Set up a peer review system where teammates read your documentation, test out your coding samples, and work through your tutorials. You’ll be glad you had a second pair of eyes to examine your docs before releasing them to the public.

Fundamental components of API documentation 🌟

There are plenty of ways to provide API guidance to your end-users: topical guides, tutorials, and support forums, to name a few. No matter what you go with, there should always be these essential sections in your docs:

• Authentication: Each API handles authentication differently, so it’s vital to describe how your API does authentication upfront. Pretend you’re a new developer and showcase the authentication process in detail, from initializing API keys to how to send them in your API requests, and anything else they might need to know.
• Error messages: Listing out every possible error message won’t make for very useful docs. Providing background on your errors and how to troubleshoot once one occurs is much more practical. (Learn more about how to write good API errors here!)
• Endpoints: Help your users understand the best use cases for each endpoint and/or set of endpoints. The same use case might have multiple ways to get the job done, so it’s critical to distinguish each of them. The more explicit, the better!
• Terms of use: Yes, unfortunately, you have to add in some legalese. But think of it as a formal way of letting developers know how to properly use your services. This section is also the perfect place to talk about API rate limits and any other constraints they should keep in mind.
• Changelog: An API is never “finished,” so you need to establish a process for updating documentation as your API evolves. This keeps your docs fresh and shows developers that your API is getting the engineering attention it deserves.

Successful API calls ☎️

In addition to the fundamentals, you’ll want to get specific about what users should expect from a successful API call. To ensure you’re not leaving them in the lurch, be sure to include:

• HTTP status code and message examples: Every error message should be documented alongside its HTTP status code, and the messages themselves should include detailed stack trace information and details on fixing the issue.
• Request parameter examples: Even if your API is extremely intuitive, providing request examples is always a good idea. Beyond explaining what each parameter does, give a real-life example for each one, so it’s crystal-clear what the API expects.
• Code samples and tutorials: Developers usually have an end goal in mind when they begin the API integration process. So why not put some code samples of the most common use cases front and center? Each sample should have detailed context for each step, as if you’re taking them on a live tour of your API. If you have the time, you can insert hints or tips on how to adjust the example to work for other related use cases.
• SDK examples: SDKs are a great way to abstract away the complexity of HTTP APIs. SDKs may include built-in types or other kinds of documentation, but that may only go so far. Be sure to reference relevant SDK examples so that users can build with your SDK successfully.
• Static vs interactive documentation: Think about buying a car — rather than just reading about it online, you want to give it a test drive. Developers also want to try before they “buy." They want to know that your API works for their use case and won’t cause any major issues before proceeding with the integration. To ease their worries, give end-users a playground or sandbox they can use to test out responses to various endpoints without deploying real code.

All together now... ✅

In a nutshell, outstanding API documentation is straightforward and educational. Review these best practices for writing API documentation to ensure your docs are checking off all the boxes. Your docs should be:

1. Making your developers’ lives easier
2. Digestible no matter the audience’s level of technical expertise
3. Well-planned and in a logical order
4. In an easily navigable layout
5. Written with appropriate, popular use cases in mind
6. Filled with examples, tutorials, sample code, and error handling
7. Clear about terms of use and limitations
8. Free of spelling and grammatical mistakes that could confuse the reader
9. Interactive, with real-life examples
10. Maintained with every release, with updates recorded in a changelog

What tools should I be using to document my API? 🛠

When you’re starting, it’s often best to use OpenAPI to document your spec. Instead of writing reference pages by hand, users can import OpenAPI files to reference pages and push changes to docs in a few seconds.

Once you’ve got a baseline API reference, it’s important to decide whether you’re going to use static or interactive documentation. Interactive documentation lets developers make live calls to your API straight from your docs. This form of documentation eliminates the need for a full developer environment in order to make API calls, saving developers time and frustration. While static documentation might be a simpler way to get started, giving live results is a much quicker way to showcase what’s possible with your API.

Ready to get started? 💪

Outstanding API documentation is the cornerstone of a superb developer experience. If your docs aren’t something developers rave about, you’re limiting your API’s potential before you’ve even started. Word of mouth is always the best advertising, so why not get that going for your API? 

If you’re looking to get started — whether you’re building from the ground-up or revamping stale documentation — we’d love to help. Our team is always happy to answer questions about API documentation and how you can improve yours. You can reach out here to get a demo and learn more, or head here to sign up for a free trial.

At ReadMe, we think a lot about creating a great experience for the developers that are building with our customers’ APIs. But we care a lot about the folks responsible for those APIs, too! Behind the scenes of every developer hub, there’s a team of engineers, product managers, and technical writers who make the magic happen ✨

Today, we're talking to Justin Jenkins from DriveWealth, who provides APIs that power investing for 100+ fintechs, brokers, and advisors across the world.

Can you share a little bit about how you wound up in your current job and what your career trajectory has been like? Have there been any surprise developments over time? For example, jobs or projects that you wouldn’t have predicted you would be doing, but were drawn to and found you enjoyed, or something similar?

Howdy! Yes, right now at DriveWealth my official title is “Sr. Product Manager, Partnerships” but at most startups, this just qualifies me as “I can do a little bit of everything.” My background is in development, specifically backend engineering working with large data sets and REST services. After building this experience in development, I started working with clients pre- and post-sale. I’ve always enjoyed working with clients and helping to solve their issues, and one of the ways we do that at DriveWealth is with our developer documentation.

Around Christmas 2022, we had a goal of redoing our documentation to be all in OpenAPI. We completed 50+ different public routes with different combinations in six weeks. On February 8 2023, the documentation launched to ReadMe via OpenAPI.  I enjoyed this project very much because the long-term result is that we can make updates easier and faster than ever before.

What drew you to working on documentation and learning more about developer experience? 

When working for startups, no matter what your official role is, one of your unofficial duties is to find and fix issues. Our developer documentation was one of the things I knew we could improve to help our external developers. The common goal DriveWealth and I had was to reduce overall integration times of our partners. Developers asking less questions on Slack means more efficient development cycles and our partners being able to launch products faster. 

Did you have any strong opinions about DX going into these projects, based on your own experiences? 

Having only been a developer and not in a position to think about other developers and their experience, I didn’t have strong opinions on DX when we started. I did have an opinion on needing a solution to solve our internal/external documentation.

What’s the most surprising thing you’ve learned in taking on these more DX-focused projects? 

That no organization out there has a formula that will work for all engineers or developers. The biggest thing we can do is recognize this fact and constantly get feedback from the developers/engineers in question to see where tooling, communication, and productivity can be improved.

Are there any misconceptions you had ahead of time that you’ve learned more about through this work? 

I would say a misconception is that, “If you build it, they will come.” The fact is, just because you add a tool or make a process easier doesn’t mean anyone will actually use or follow it. Let’s be honest, some developers are lazy — not all, but some! And even if they aren’t, they’re probably busy and have a million other things on their plate. So if using your new process or tool means learning something new, you need to remember that and keep it in mind as you introduce and onboard users. 

What are the most important lessons you’ve learned, and how have they impacted the way you approach your day-to-day work?

I’ve learned that context in reviewing a PR on publicly facing documentation is extremely important. The more information a developer can provide on the “why” behind a change, the better. As a reviewer, we may not know the context or may have lost the context, because it was discussed weeks ago. When developers err on the side of providing more information, it helps the content reviewers review more quickly and give better feedback when necessary. 

What are your favorite resources for learning more about developer experience, APIs, and documentation? 

My favorite resource is attending conferences or like-minded meetups. I can always read about different approaches to things like developer experience, APIs, and documentation, but that information is always in a silo. I learn the best from those road-to-rubber moments that come from speaking to others at more mature organizations and their methods. Hearing about real applicable experience/metrics from others is a great way to better inform our organization of the specific benefits of a process and/or tool. 

What would be your top piece of advice for someone who wants to learn more about these kinds of projects and incorporate them into their work?

I’d say if you're working in developer experience, then the goal is to be constantly improving. Just because you get to a state where things are good doesn’t mean you should stop — change your POV a little and you can probably find something else that needs improvement. And have fun with it! 

Thank you, Justin!

We're excited to hear more about the new developments at DriveWealth, and you can learn more about their experience with ReadMe in their customer story.

More about Justin:

Hey, I’m Justin Jenkins, a Senior Product Manager, Head of Partnerships at DriveWealth. My passions are solving complicated problems with tactical solutions for people and technology. In my spare time, I like to think I’m a great salsa dancer and car enthusiast. I’m always driven by the need to understand what is next and what is needed to overcome the current objective. I am super excited about the advancements in DevEx and technology, and how we can bring that knowledge to DriveWealth.

Welcome to the first ReadMe in Review of 2024! We know how busy it is during the holidays, so we’ve collected all of our news and updates from last month in one spot for easier perusal. 

Of course, our biggest update from December was the Reusable Content release. If you want to read more about what’s included in that, you can head here. Ready to set it up? Our docs can help you get started. 

Other than that, let’s see what the team got up to last month: 

Owlbot AI 🤖

• You can now customize how Owlbot responds to questions, including tweaking the tone, adjusting the length of responses, and setting a default response for times it doesn’t know an answer
• You can also now prevent Owlbot from using specific words in its responses (for example, names of your competitors)
• On Enterprise plans, we added API access to ask OwlBot AI questions programmatically, which means Owlbot can be embedded directly within a product or wherever else users might need easy access to documentation (learn more here)
• We’ve also updated the AI model to give more detailed responses and account for larger prompts (via GPT-4 Turbo)

SEO improvements 🔍

• We’ve added more granular control over SEO settings for documentation hubs, including disabling robots.txt on a per-project basis, adding a noindex tag to specific pages, and editing metadata keywords for pages 
• When editing SEO metadata, you can now automatically generate a short description of the page with AI

Other changes and updates 🪄

• We’ve created a new Slack group for ReadMe users to ask questions and share their experiences — join here! 
• In Developer Dashboard, Try It requests will now populate with user emails if the user is logged in, without any extra configuration required
• In the editor, callout headings are now H2 tags for better accessibility, and reordering pages is now faster and more reliable 
• For SAML users, we’ve added an optional redirect URL upon logout

That’s all for this round! If you want more details on the product updates and improvements, head to the ReadMe changelog to get the scoop and stay up to date as these changes are announced. We’ll keep you posted on any upcoming events or other news, but in the meantime, if you have any questions, feel free to reach out to our team. We hope your January is off to a great start! 🎉

The year is almost over, but before we officially say goodbye to 2023 and hello to 2024, we have one more holiday treat: we’re launching the new Reusable Content feature today! We know this is something many users are excited to see, so we’ll cut right to the chase.

Introducing Reusable Content

The concept behind Reusable Content is fairly self-explanatory: it allows Project Admins to create blocks of content that can be used across multiple pages and locations. When the Reusable Content block is edited, the content automatically updates everywhere that block has been used. Not only is this a huge time saver, it also means that you don’t have to worry about stumbling across an outdated page section that got skipped over when that content was updated elsewhere in your docs. 

Reusable Content acts as a block, and you can find it in the editor’s slash menu:

The Reusable Content block isn’t just for text — it supports all Markdown, so you can include images, code snippets, callouts, and more. To see a full list of blocks that the Markdown editor supports, you can head to this page in our docs. 

Right now, Reusable Content is available to Business and Enterprise customers. Business customers can create, edit, and add Reusable Content blocks to pages in their project. Enterprise customers have a global Reusable Content page for creating and managing blocks that can be used across child projects, as well as being able to create blocks at the child project level that can only be used for that specific project.

Streamline your workflow

When we created Reusable Content, we were thinking about our users that spend the bulk of their time in ReadMe using the editor to create and update their documentation. Because of that, we’ve designed this feature to make it as easy (and efficient) as possible to update and maintain documentation.

Whether you want to…

• Include version specific content
• Add relevant callouts for specific plan types or user groups
• Ensure that all related pages link back to one another
• Answer frequently asked questions

…or do something else, Reusable Content blocks make it easier to scale your documentation production and update processes. Part of that is that Reusable Content makes it easier to share editing responsibilities across multiple people, since the blocks are visible and usable by all Project Admins.

Improve your DX 

Streamlining the update workflow doesn’t just save you time — it also means there are fewer manual edits and more automated updates, which leaves less room for human error. Reusable Content blocks also make it much easier to unify how concepts are communicated and repeated through your API documentation. 

For example, if you realize after you’ve created a block that it answers a commonly asked question, you can always turn it into a Reusable Content block after the fact, and add it to other relevant pages in your hub:

And of course, when you spend less time manually updating your docs, you can spend more of that time giving hands-on help to your developers. 

Ready to start reusing?  

As of today, Reusable Content is available to users on Enterprise and Business plans, so you can start using it now. If you’re not currently a ReadMe user, you can test it (and all of our other features!) out by signing up for a 14-day free trial. And as always, if you have any questions, feel free to reach out to our team — we’re happy to answer your questions and give you a tour!

Our team has been hard at work improving the ReadMe experience, and with so many updates, it can be hard to keep track of all of them. We've got you covered, though, with ReadMe in Review, here to summarize all of the changes and news from last month in one spot. 

Let’s see what Owlbert’s gift bag has in store for you this month:

Owlbot AI 🦾

• If you’re using Owlbot AI, you can now export the questions your customers asked as a CSV, and you can now also use filters to narrow down the data set
• Indexing improvements, including hourly re-indexes (as opposed to every other hour) and an improved ability to handle especially content-rich pages 

API Reference & Developer Dashboard 📊

• API Keys in the API Reference section are now sorted by most recently used
• ReadMe now renders OAS file information directly in the Getting Started page; you can enable and configure the Getting Started page by going to API Reference → Developer Dashboard → Getting Started
• Developer Dashboard users will now be notified when making an export that exceeds our limit of 1 million rows
• Added the ability for users to view their API calls directly in the reference section under the “My Requests” header

Other changes & updates ✨

• Changelog: Added more design customization options, including date formatting, author visibility, and text layout
• Accessibility: Made small changes to API Reference and navigation UI to increase contrast to a minimum of APCA Lc60, along with making accessibility improvements to code snippets, Owlbot AI, and the sidebar
• SEO: Added options to include keywords for pages and include/exclude projects from your robots.txt file
• Login preference: Users can choose to log into the documentation hub via an emailed link or by setting up an email and password, and ReadMe will now remember their preference when they log in in the future 

Meetups & events 🍻

November was a busy month for meetups and events! We had booths at GitHub Universe and AWS re:Invent, as well as hosting a meetup at Thriller Social Club on the 8th. Our team had a great time meeting new people, seeing familiar faces, and testing our skeeball skills at the meetup.

That’s all for this round! If you want more details on the product updates and improvements, head to the ReadMe changelog to get the scoop and stay up to date as these changes are announced. We’ll keep you posted on any upcoming events or other news, but in the meantime, if you have any questions, feel free to reach out to our team.

When considering what makes a great developer experience, we usually break it down into the three stages of your developer lifecycle:

• Evaluation & onboarding 🤔 Educating users about what’s possible and helping them make their first API call as quickly as possible
• Engagement & support ❤️ Giving users the tools to build efficiently and helping them debug issues when they run into roadblocks
• Retention & growth 📈 Driving adoption of new API features, increasing usage over time, and ensuring a smooth transition for users to new API versions

Supporting this full developer lifecycle — from the first call through long-term integration — is what we aim to do here at ReadMe. Creating a great experience for your API users is no different than for any other product: the exact tactics you use may vary, but at the end of the day, you’re helping people with a problem to solve and a job to do. 

What’s possible with your API? How can your developers start building? And what can they do when things go wrong? These are the answers users are looking for in your developer hub, and we’re excited to help you deliver them ✅

Introducing Developer Dashboard

API teams talk about “Time to First Call” as a north-star metric for their developer experience: how quickly they can engage and enable a new developer to make their first API call. There are several things that go into this process (and several potential pitfalls along the way), so we’ve recently shipped improvements across the entire ReadMe experience to make this simpler for new users. Together, these features make up your Developer Dashboard, baked directly into your ReadMe dashboard and hub 🎉

Lowering the on-ramp for new users 

Instead of giving users complicated instructions on how to hunt down their keys, bring the keys into your hub exactly where they’re needed! ReadMe’s Getting Started & Authentication pages give users instant access to their API keys so they can jump in right away. With their API keys front and center, new developers can easily use the Try It playground to send their first authenticated request 🙌

After they’re up and running, their API keys are easily accessible in Try It anytime they’re checking out a new endpoint. Server variables or other custom data can be piped in too, so everything they need is at their fingertips:

In addition to improving the developer experience in the hub, we’ve also improved the onboarding experience for ReadMe Admins by streamlining the setup process for these features. Now, both the “Set Up API Keys” page and the “Set Up API Logs” page are unified under the My Developers area of your project dashboard, with clearer indications of what’s been configured and what setup steps still need to occur.

Getting on the same page to debug issues

You’ve made it easier for new users to get started — now what? Inevitably, they’ll run into issues (it happens to the best of us!), so making the debugging experience as efficient and painless as possible is the next priority. 

Your first line of support should be to give users the tools to try to debug on their own. If they can figure out what’s going on in a few minutes and avoid waiting for a support ticket to be answered, that’s the dream 🌠 Now, users can see their previous requests for all API keys they have access to on the My Requests page in the API Reference, so they can quickly dig into failing requests and see what’s going on. 

Using quick filters for endpoints, method, status, and/or user agent, users can hone in on failing requests (and check to see what’s different about their successful calls). They can also click into any log to reveal even more details related to their request and response.

Alternatively, users can navigate to the endpoint page to replay any individual log in the Try It playground to dive deeper. Bonus points for extra helpful error messages that give them a hint at what’s gone wrong 😎

And for ReadMe Admins, we’re taking this debugging workflow a step further with My Developers, in-depth developer profiles where your team can dig into API usage and quickly debug issues. Just as we surface API keys and real-time logs to end users in your developer hub, My Developers gives your team the backend interface to see who’s having issues, identify fixes, and seamlessly support your developers to get them back on track.

Powered by your real-time API request logs, the magic of My Developers lies in filters ✨ By honing in on certain endpoints, methods, and status codes for a given time period, you can build and save segments to monitor usage of your APIs: 

• Track who’s getting lots of 🔴 400s this week to reach out and offer a helping hand
• See who’s using the endpoint you recently launched 🚀 to get feedback on their use cases
• Look up a user’s logs 🔍 when they write into support to help them debug issues

And when users write into support with an issue, Admins can quickly look up a user by their API key, email address, or company to jump into their logs and see what’s going on. No more copy and pasting request code back and forth in emails to try to get support reps on the same page — with ReadMe, users in the hub and admins behind-the-scenes can look at the same logs together.

Supporting your users in the long run

With the foundations of your API onboarding and debugging experience in place, it’s time to look toward the future 🛣 In addition to the vision for your APIs coming from your team, ReadMe gives you valuable insights to help inform these decisions. You can easily track usage metrics, like API adoption over time and API error volume, to see where users are getting stuck.  

The Home screen also provides an at-a-glance snapshot of your Docs Metrics where you can see your most popular pages and search terms, and track new users over time. These metrics can inform what pages to prioritize updating, or to see what pages might need to be labeled differently based on high volume keyword searches.

Together, all of these insights bring a data-driven lens to decisions about where to add features and invest resources to improve your API and documentation. You can also export your metrics data as a .CSV file for further analysis or cross-referencing with other data. 

As you ship new versions or deprecate endpoints, My Developers makes it easy to diagnose who will be impacted so you can proactively reach out and help them through the transition. And as much as we don’t like to talk about security incidents 😬 in the event of an API key leak, you can quickly pull a list of keys that were active during the affected time period for communications around revoking and rotating their keys. You’ll be happy to have the tooling in place to support your team in these moments (infrequent as they may be): hope for the best, plan for the worst!

What’s coming next 

You’re here to support your developers, and we’re here to support you! We’d love to hear your feedback on Developer Dashboard as you start exploring the features and functionalities. Head over to the docs to learn about all the features and benefits of the full Developer Dashboard experience 🎉 Access to 24 hours of data is included in every ReadMe plan, so you can take it for a spin worry-free.

It takes a lot of dedication to create and maintain excellent documentation — but if your developers can’t find the information they need when they need it, that effort was all for naught. And that discoverability problem only increases as you add more content to your developer hubs.

To help you solve that problem for you and your developers, we created Owlbot AI: a new way to enhance your developer experience across your documentation. Owlbot AI is a chatbot that lives inside your hub’s search, so developers can ask Owlbot their questions and get an instant response. It’s your docs, made better and more powerful 💪

What exactly is Owlbot AI? 🤖

The standard search functionality included in ReadMe pulls up relevant information based on keywords that the user types in. On the other hand, Owlbot AI is trained on your documentation using the power of GPT-4 and GPT-3.5 Turbo. It goes a step further than keywords by “reading” the information in your developer hub and generating an answer based on that information. In addition to supplying an answer, Owlbot AI also links to the pages that the information was pulled from, so the reader can get as much extra context as they need.

Owlbot AI is integrated into the search experience, which means that it’s accessible on every page of the hub, ready to guide your developers whenever they need help. After typing in a question or keyword string, the search results and Owlbot’s answer are shown in the same place. This way, the querent can get the highlights, while having further information easily accessible if they need it.

Learn more about your developers 🔍

After Owlbot AI is enabled, you’ll be able to see a dedicated page for it in the Project section of your dashboard. Here, you can see all of the questions that visitors to your hub have asked, and what answers were generated.

When Owlbot AI creates an answer, querents have the ability to upvote or downvote the answer based on how helpful it was (or wasn’t). By looking at the questions that your developers are asking and which answers were upvoted/downvoted, you can learn more about what people are looking for. It’s also a great way to keep an eye on which pages of documentation may need to be added, updated, or clarified.

Your data stays private 🤐

Venturing into the territory of AI often comes with privacy concerns, so it’s important for you to know that none of your data will be used to train any of OpenAI’s models. Your project data is only used to answer specific user questions, after which your questions and answers will be stored by ReadMe for the admin UI, and OpenAI retains logs of API requests for 30 days. You can read more about OpenAI's data usage policies here.

Owlbot AI uses your Guides, API Reference, and Discussions pages to generate answers, and hidden pages are never indexed or used to create answers. This keeps your private content private, as Owlbot AI will only use content from the pages that your readers can see in the sidebar. For Enterprise ReadMe users who use permissioning features, only the content the user has access to is used to answer questions. If a user is granted permissions to see Project A, but not Project B, none of the content from Project B will be used to generate answers for that user.

How to get started 🚀

If you’re a self-service customer, you can enable Owlbot AI on the Owlbot or Manage Plan pages in your dashboard:

If you're an Enterprise user, you can get started by navigating to the same page and contacting your CSM. After Owlbot AI is enabled, the admin UI will be visible on project and group dashboards.

Want to learn more? You can get more details and request a demo here. And, as always, if you have any questions or want to share your thoughts, we're just an email away. You can also get in touch by sending a message via the Intercom widget in your dashboard or hub, or reach out right now by clicking on the icon in the lower right-hand corner of your screen. We'll happily help you find what you're looking for (just like Owlbot! 🦾).

ReadMe already makes it easy to create great developer hubs for public and partner APIs. But we know that companies often have hundreds (if not thousands!) of internal APIs to track, and that tracking and documenting that many APIs can be something of a logistical nightmare 😱

That’s why we’ve created ReadMe Micro. With it, our goal was to create an elegant solution for engineering teams looking for a better way to organize and maintain their internal APIs and microservices. Think of Micro as a developer hub for your engineering team: one centralized place to discover, organize, and share all your company’s internal APIs. To get started, select all the repositories in your GitHub organization or Bitbucket workspace with the OpenAPI files you want documented. You’ll have a new Micro developer hub in no time!

Masterful docs with minimal work 🎨

Documentation is crucial to keeping your API users happy, but creating and maintaining excellent docs is a job in and of itself. At the end of the day, internal APIs (and their users) often don’t get the same level of attention as external APIs. Without some sort of hub or homebase for those internal APIs, it’s hard for engineers to find them and learn about how they work and what the best use-cases are. This is frustrating for the engineer in question, and often leads to duplicated or delayed work.

As a team building a product by engineers, for engineers, we wanted to make those problems disappear, and Micro is our solution.

Once a GitHub or Bitbucket repository with an OpenAPI file is connected, Micro auto-generates a polished and professional API Reference for it, where you can copy and paste code samples and add more information. Preview versions of your docs are generated for every PR, and the continuous deployment process includes built-in linting and validation, so issues are caught before they hit your actual docs.

Docs writers can then add a Markdown file to provide more instructions or helpful tips for each connected repository. This significantly cuts down the amount of time a team has to spend creating documentation, while still creating professional, easy-to-use docs. No more lists of OpenAPI files living on a static page!

Maintenance made easy 🛠️

After that initial setup, changes made to the synced OpenAPI files in GitHub or Bitbucket are automatically synced to Micro. Then, the changes are noted in a changelog that’s also automatically generated for each repository. Users can see recent updates and changes at a glance, and they can also switch between versions (if you choose to create them) with a simple dropdown menu.

Easy to use, easy to find 🔍

Of course, having automatically generated docs doesn’t do an engineering team any good if it’s impossible to find the documentation you need at any given moment. Micro’s search functionality lets you search and filter by attributes like name, tags, or time synced, and you can also add topics to specific repositories for easier and more accurate searching. Have an API you use on a regular basis? You can bookmark it, so that it’s always easy to find ⭐

Now, teams have all of the info they need to start using your APIs quickly, and don't have to worry about manually updating files.

Stay secure 🔐

We know how important security is and that you may be wondering exactly how much data you’ll have to share for all of this automatic creation and syncing to function as designed. We’ve worked hard to ensure that Micro requires as little data access as possible, and we’ve designed the access model to be completely open-source. If you want, you can even audit our repository scanning tool and confirm that Micro only reads the files from your repository that it needs (e.g., your OpenAPI file) — nothing more.

What’s the limit? 📈

ReadMe Micro’s pricing is user-based, rather than being based on synced APIs or repositories. We felt that basing pricing on either of those things would work against our goal of making documentation that is scalable and accessible for internal teams. Because of that, pricing is set at $10/month, per user, per organization. If you want to learn more about bulk pricing, you can reach out to our sales team to set up a demo and discuss pricing for your organization. And no matter what, your first 30 days are always free for you and your team to try out Micro.

And that’s not all… 👀

ReadMe Micro is live and available to use for private APIs. Very soon, you’ll be able to use it for public APIs as well — if the repository is public on GitHub or Bitbucket, it will be public in Micro. Of course, that's not all we're working on, so watch this space for future updates 💫

Learn more with a personalized Q&A 📝

As always, we’re happy to answer your questions and listen to your feedback. In fact, we’re hosting two virtual office hours sessions on Thursday, September 21th at 10 AM and 2 PM Pacific. Greg, our founder and CEO, will be there to give you a live walkthrough and answer all of your questions, so you can get a deeper overview and learn more about Micro, learn how to best set up their organizations and sync their repositories, and ask any other questions you have. The sessions will be Zoom calls and capped at 50 attendees each. To learn more and sign up for your session of choice, head here.

Can’t make the sessions but still want to learn more? Reach out to the sales team here and they can get you sorted ✨

Long-time followers of the ReadMe blog know I have been absolutely shameless in my love for 1Password. It's a great password manager that we use here at ReadMe to securely store shared logins, API keys, and more. Staying secure online is increasingly difficult these days, and we’ve been able to safely rely on 1Password for best-in-class security with a convenience and user experience that lives up to one of our core ReadMe values: “strive for simplicity.”

So it should come as no surprise that I’m very stoked to announce ReadMe's partnership with 1Password. With the ReadMe shell plugin for the 1Password CLI, together we’re making your experience with ReadMe’s developer tools even more convenient and secure. Get the details below! 🤝

Juggling API keys: a necessary DX evil 🤹

Let’s first start with some background. Over the last year or so, we’ve been making several improvements to the developer experience around API keys in ReadMe:

• A secret scanning partnership with GitHub to automatically revoke exposed ReadMe API keys and notify our users ♻️
• The ReadMe API key management dashboard which gives you the ability to provision multiple keys for your project and makes it easier to rotate keys out 🔄
• Interactive Getting Started and Authentication pages in the API reference section, where you can browse your ReadMe API keys and make authenticated requests to the ReadMe API directly from the docs (and yes, you can also set these pages up for your users!) 🔑

While these changes have been great from a security and developer experience standpoint, none of these could possibly address a common problem amongst developers: juggling lots of API keys. Figuring out where keys came from, rotating keys, maintaining separate keys for separate environments/users…the list goes on! It’s a necessary evil for developers when a key inevitably gets leaked 🙀

Our knowledge base has grown to the point of switching over to a multi-project setup for our docs. Because of this, we’re now working with many API keys across several ReadMe projects, which is also the case with many of our Enterprise customers. And once you start dealing with multiple API keys that you’re sharing with your team, it can get chaotic rather quickly.

1Password has proven to be a useful management tool for API keys not only because of its security, but also because you can jot down notes for a given API key. You can use this to provide helpful context for fellow engineers, like expiration dates, links to management dashboards, where it’s used, etc. While it’s easy enough to store these credentials in your password manager, what about using your password manager as the single source of truth so you can load secrets into your developer environments in a secure, automated way?

Luckily, 1Password introduced shell plugins, which are integrations that securely pass API keys into your favorite command line tools, including gh (the GitHub CLI), twilio (the Twilio CLI), and (you can probably guess where I’m going with this…) rdme (the ReadMe CLI)! Let’s dive into the ReadMe shell plugin below.

Say hello to the ReadMe shell plugin 🐚

With the ReadMe shell plugin set up, you can keep your ReadMe API key in 1Password and securely pass it into your rdme commands. What does this look like in practice? A quick scan of your fingerprint (if you’re a macOS user):

Pretty slick, right? Let’s walk through how this all works:

• First, make sure you have the latest version of rdme, the 1Password desktop app (Mac or Linux only), and the 1Password CLI (version 2.12.0 or above) installed 💿
• Next, set up the ReadMe shell plugin for the 1Password CLI. This will create (or import, if it already exists) a 1Password item that contains your ReadMe API key 🐚
• Once everything is set up, 1Password CLI will listen to your terminal for rdme commands that require authentication (i.e., authenticated commands like rdme openapi are listened for and non-authenticated commands like rdme --help will be ignored) 👂
• When a rdme command is executed that requires authentication, the 1Password CLI will prompt you for your fingerprint (or whatever authentication setup you have for the 1Password app) ☝️
• The 1Password vault is unlocked, your ReadMe API key is securely passed into the terminal command, and rdme is connected to your ReadMe project 🚀

While this approach to passing credentials into rdme is both convenient and secure, do you want to know what’s my favorite part about this experience? If you’re juggling many API keys across several ReadMe projects like we are, you can store all of them in 1Password and have the ReadMe shell plugin confine your credentials to a specific directory or terminal session.

With the ReadMe shell plugin, you’ll be an expert API key juggler in no time!

Some bonus “action” 🎬

But wait, there’s more! As an added benefit of securely storing API keys in your 1Password vault, you can safely load them into CI/CD environments, like GitHub Actions. This is great news, because rdme happens to have first-class support for GitHub Actions!

Here’s yet another great example of how 1Password and rdme can work together in harmony to securely sync a directory of Markdown files to ReadMe:

# Runs on every push to the `main` branch
on:
  push:
    branches: [main]

jobs:
  sync-to-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Load secret from 1Password
        uses: 1password/load-secrets-action@v1
        with:
          # Export loaded secrets as environment variables
          export-env: true
        env:
          OP_CONNECT_HOST: <Your Connect instance URL>
          OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
          RDME_API_KEY: "op://engineering/readme/api-key"

      - name: Sync OpenAPI file to ReadMe 🦉
        uses: readmeio/rdme@v8
        with:
          # `rdme` automatically reads the `RDME_API_KEY` env variable
          rdme: docs ./documentation

Let’s break down what’s happening in the example above:

• This workflow kicks off when a commit is pushed to the main branch of your GitHub repository.
• 1Password’s GitHub Action establishes a secure connection to 1Password, grabs the ReadMe API key value and exports that as an environmental variable called RDME_API_KEY.
• The rdme GitHub Action automatically detects RDME_API_KEY as an environmental variable containing your ReadMe API key, and uses that to sync your Markdown docs (located in the documentation/ folder) to your ReadMe project.

With the power of 1Password and rdme, you can securely sync your docs to ReadMe — whether you’re working in the command line or in a GitHub Actions runner 😌

Now let’s get you plugged in 🔌

Ready to start syncing? The integrations described above are available now:

• Head over to the 1Password Developer docs to get the ReadMe shell plugin up and running 🐚
• Check out our docs on setting up the rdme GitHub Action and 1Password’s docs on loading secrets into your GitHub Actions workflows 🌊
• Check out my appearance on the "The Developer Special" episode of 1Password's "Random but Memorable" podcast. We have a wide-ranging conversation about 1Password's developer tools, developer tools in general, and upcoming projects we're cooking up here at ReadMe 🎙️
• Join us on May 11th in SF at API Mixtape, where we'll be talking all things developers with folks from 1Password, Twilio, and more. Use the code 1PASS for a free ticket (hurry, just a few of these codes are available!) 📼

We’re always looking for ways to make ReadMe’s developer tools safer and more enjoyable to use. If you have any feedback about your ReadMe experience, feel free to reach out to us at support@readme.io or open up an issue in the rdme repository. We’d love to hear from you! 🦉

When it comes to documentation, it’s easy to focus on the reader experience — is it well-written? Easy to skim? Full of helpful code samples for getting started?
But creating that documentation should be a great experience, too. And most importantly, when making updates is a breeze, you’re more likely to keep your docs up-to-date for your users.

With that in mind, over the last year our team has been working on a new version of our Markdown editor focused on creating a lightning-fast, intuitive writer experience. We’ve also revamped the sidebar and page controls to make organizing your docs simpler, and better match the experience of the new editor.
Today, we’re thrilled to announce that the new editing experience is live. Keep reading — we’ll show you around 🥳

Get to Know the New Markdown Editor 👋

Our goal with this editor was to combine the best elements of Markdown syntax with the previewing abilities of WYSIWYG editors. We aimed to remove any unnecessary steps like the need for a separate “preview” mode and instead allow you to see your rendered text styling in real time. We also wanted to prevent the dreaded experience of finding yourself stuck in WYSIWYG mode, with no clear path back to plain text. Showing the Markdown syntax makes it easy to see where the formatting stops and starts, so you can focus more on writing your docs and less on fiddling with formatting.

The next time you create or edit a page in ReadMe, you’ll notice Owlbert welcoming you to the new editor experience and sharing a few tips. Here’s a few highlights of what to expect 🦉

• Quickly add headers, images, tables, and other embed blocks with the new slash command menu — just hit “/” to get started 🧱
• Easily copy and paste Markdown content into ReadMe, while maintaining all of the syntax and formatting, making content migrations a breeze ✂️
• Make quick formatting changes with a new in-line hover menu to bold, italicize, strikethrough, or link any highlighted text 🖌️
• Prefer to skip the menus? No problem — you can always format text using Markdown or use keyboard shortcuts to get the same results ⌨️

Build Great Docs with Blocks 🛠️

Our philosophy is that good docs aren’t just about words on the page — they’re about showing users the information they need to quickly get started or troubleshoot their problems. Being helpful and accessible is essential, but we’d argue they can (and should!) be fun to use, too 🎊

Embeds are a great way to do that — following the age-old writing advice of “show, don’t tell”! So we’ve updated everything about our docs blocks to match the new Editor features. Using embeddable blocks, you can:

• Surface useful examples and tutorials with code sample blocks and Recipes 🍳
• Embed content from third-party sites, like GitHub Gists or Loom videos, to support your written documentation with tutorials and demos 📹
• Use callouts, GIFs, blockquotes, and dividers to break up large blocks of text and give your docs some personality 😎

Find Your Way With New Navigation 🧭

The new editing interface isn’t the only improvement we’ve made to creating docs. Our fully redesigned sidebar makes it easier than ever to take a visual inventory of your docs and re-organize them to your heart’s desire 💞

With our newly revamped sidebar in Guides and API Reference, you can:

• Collapse pages into categories or their parent pages to make your content easy to scan 🔎
• Use the improved drag-and-drop UI to easily move pages between categories or re-arrange categories within your sidebar 👉
• Rename, delete, and move pages between sections from the three dot menu next to all pages and categories 🎲
• More easily access your project’s API Definitions, Getting Started, and Authentication pages, which are now anchored at the top of the API Reference section of the sidebar ⚓️

Our page controls have also gotten an upgrade — it’s now easier to view and change your page type, switch between your page’s status (public vs. hidden), and edit a page’s metadata. Plus, our upgraded Page History simplifies tracking changes between versions. Versions are now grouped by month and are collapsible, so it’s easy to go as far back as you need to to find the version you want.

Let End Users Give You a Hand

Why keep the new editing experience to yourself? We’ve upgraded our “Suggest Edits” feature to showcase a version of our new Markdown editor so that your developers can try it out too!

Whether a developer catches a simple typo or proposes feedback, enabling Suggest Edits makes it that much easier for you to know what changes are needed in your docs and crowdsource that help from your community! The Discussions section has also gotten an upgrade, so your developers can ask questions in style 🤩

Now It’s Your Turn ⏭️

You can watch a full demo on the new experience here, and read our docs on the new editor here and on the upgraded sidebar and page controls here. Most importantly, we hope you jump in and try it out. We’ve worked hard to make the new editing experience as delightful as possible, so we’d love to hear what you think ✨

Speaking of hard work, we want to take a moment to recognize all of the ReadMe team members who worked to bring these new experiences to life: Aaron Hedges, Brendan Luna, Daniels Lee, Ellie Rossuck, Ilias Tsangaris, Julia Hotaling, Kelly Price, Kevin Ports, Naomi Day, Rafe Goldberg, Ryan Visek, and Trisha Le 👏

As always, if you have any questions about it (or anything else), feel free to reach out via email at support@readme.io, or by sending a message via the Intercom widget in your dashboard or hub. Happy editing!

Recently, we co-hosted an AMA (Ask Me Anything) webinar with Josh Nickerson, Senior Manager of Product Management for Amazon API Gateway, and our founder & CEO, Greg Koberger. Over the course of the hour, Dave (the moderator and VP of Sales here at ReadMe) was able to ask them audience questions covering everything from the future of APIs to getting leadership buy-in on new API initiatives. Read on to find out what they said, and if you’re curious about our partnership with AWS, you can learn more about that here.

Editor’s note: Answers have been lightly edited for brevity and clarity.

Driving API Adoption

What are the must-haves if you’re launching a new public API at your company?

Josh: There's a lot to keep in mind, but availability and security are my top two concerns:

• Availability: You should have an idea of how much traffic you’re expecting and be confident that you can handle it
• Security: You want to be confident that you’re not opening up your systems to a potential data breach

Other potential concerns include:

• What sort of authentication authorization setup do you have? Will this be an open API that anyone can use, or do you want to know the details of and set permissions for users?
• How are people going to find out about the API? As you launch multiple APIs and package them into products, what scalable tools are you using to document and share them?

Greg: My biggest concern before you start: have strong use cases for why someone would use your API. People launch APIs and then nobody uses them, because the endpoints don’t make sense for real-life use cases.

Avoid the “build it and they will come” mentality — you’re asking people to dedicate resources, time, effort, and trust. Make sure there are very clear use cases that people are actually excited about and accommodate those use cases when building the API. Focus on knowing what it is that users want to build and designing your API to give them a head start on that.

After launching your API, how do you gather and prioritize developer feedback?

Josh: There are a lot of key factors to take into account:

• What's the input? How are they going to give you this feedback? Built-in feedback options on documentation, emails to your team, a support forum? Whatever they’ll be doing to share feedback, make it as easy as possible.
• What are you going to do with that feedback when you get it? How will you prioritize issues, estimate the resources it will need to fix them, and incorporate those fixes into development sprints?

Greg: I notice that developers have a tendency to “just figure it out” and often don’t raise their hands to ask questions, which can result in developers:

• Assuming that the problem/issue is their fault
• Getting frustrated and moving on, writing off the product/API as a result

That self-sufficient DIY mentality is one reason docs are so important; it’s also important to actively solicit feedback to counteract it. Not just via thumbs up/down on docs, but also watching metrics for errors on specific endpoints and reaching out to users to help fix that problem. In watching for and then being proactive with with ReadMe errors, we’ve improved the documentation and fixed bugs, but also made customers happier and gathered valuable feedback.

What metrics do you look at to understand API health?

Josh: Depends on the targets you have for the API, but in general:

• Engagement and growth relative to the targets you have. How many people are using it? Is that number growing?
• Operational metrics like error rates. Are you seeing fatal errors? What’s the error trend-line look like? Is latency relative to where you want it to be?

Then, depending on what the API is, others can come into play from a security perspective or a monetization perspective, but those are common top ones.

Greg: It's very important to look at not just big picture graphs/metrics, but that’s not enough — it tends to fall apart when it comes to early users. Things to consider:

• The sheer volume of API calls you get (in general and from heavy users) can easily skew success percentages
• Looking at new customers and their usage metrics can help offset that and keep you from losing early users when they run into errors
• People interact with APIs in two major ways: actual developers trying to get a response back, and in production with the API running behind the scenes
• Separating those scenarios is important, something running like clockwork for a year+ is a different data set than the people making changes and trying to make something new happen (and potentially running into errors)

I agree with everything Josh said, but I want to emphasize that it's important to realize every failed API request is a real person trying to do something for real, for their customers, for themselves, etc. Make sure it's easier to highlight those very few small amounts of errors, especially with new users.

The State (and Future) of APIs

How do you see the API landscape changing in 2023 based on the startup tech market right now?

Josh: It’s important to recognize that cloud and serverless operation is still pretty new. The move to microservices and API-first is a newer trend — I expect that trend to continue and only get bigger from here. That trend will likely accelerate because companies get cost savings when they don’t have an in-house data center and they can decentralize things, make them more modular. That ability to move faster becomes important in times of economic shifts.

Security is big factor; the threat landscape and potential of bad actors isn’t getting any less scary. I expect emphasis on API security to continue with more scrutiny around data breaches and protection of sensitive data.

More emergence and refinement of industry-specific API standards. OpenAPI already exists, but we’re seeing open banking, open charge point protocol, fast healthcare interoperability requirements, etc. For example, there are government types of customers in public sectors where, if you're building an API in this kind of space, it needs to meet specific requirements and standards. Companies need to take compliance and regulations into account. It's important for API providers to think about how they can make it easier to manage those requirements.

Greg: It's less about this year in specific, but I’ve always thought there will be a convergence (if not a complete one) between traditionally technical/non-technical people and roles. 10 years ago, if someone said they worked on APIs, it would be a near-guarantee they’re a developer, but that’s not necessarily the case now.

The line between technical and non-technical is getting more and more blurred; people are becoming more technical just due to growing up around technology, as well as tools becoming easier and easier to use. More and more people are able to take advantage of tools that have traditionally been locked up in this highly technical knowledge.

The last thing: I’m really intrigued by companies that are realizing that developer tools don't necessarily mean users have to build everything from scratch or go for the most complex solution. Seeing more and more “choose your own adventure” type options that let users set the level of complexity to match their comfort level and goals. The best tools can meet customers at every single level based on their needs; I expect to see that more and more over the next few years and I’m looking forward to it.

How do you think the emergence of AI will affect the API landscape?

Greg: This is a good dovetail with last answer. An example: As an engineer, OpenAPI’s API can be frustrating, because it uses prompts, which can feel unpredictable when used to standard coding methods. At the same time, it’s fascinating and interesting, and a good showcase of changing how people think about interacting with the system. Before, we’ve always interacted with systems after letting computers do most of the decision-making about how we talk, since they need specific structure.

AI flipped that, so that we’re no longer communicating on the computer’s terms. I expect this to bring more and more people into the field and make it easier to do more and more complex things. I’m excited to see what it will look like to interact with computers in 5, 10, 15 years with some of these changes/evolutions.

Josh: I've worked in Alexa AI for three years, owning internal machine learning platform that Alexa scientists and engineers used to build a different model. After that experience, I have two thoughts:

• Agree with what Greg said earlier — AI and the emergence of AI will make it easier for people to build APIs
• What’s happening in machine learning parallels what happened in the previous software generation, where we’re seeing machine learning ops (similar to dev ops) emerge; people want to track the evolution and lineage of a model across lifecycle from raw data to model to in production

APIs play into all of this and it’s something we need to start thinking about as we build APIs. Does this enable a machine-learning driven use-case? Does it plug into their data pipeline or machine learning ops? These are some new things to consider when thinking about business cases for an API.

How can employees make an effective argument for getting more resources for API efforts?

Josh: Two things come to mind from how Amazon operates:

• Being data driven: You need to understand what the ROI is, whether that’s in terms of cost, time, productivity, etc., and be able to clearly communicate that
• Customer obsession: What’s the voice of the customer here? How does what you want to do with the API relate to what customers are asking for? Can you bring in direct quotes from customers to back this up?

Potential third consideration: pattern recognition. Point to other successful examples of companies that did something similar and it worked out well for them.

Greg: 100% agreed. Make sure you’re tracking metrics from the jump, so you can showcase how many people are using it and how they’re using it.

When should you consider switching API service providers?

Greg: If you're thinking about switching to ReadMe, do it now. If you're trying to switch from ReadMe, maybe that's more of a 2024 thing? 🤔

Josh: Ditto for Amazon API Gateway and AWS more generally. Aside from that, returning to availability and security:

• Availability: Can they support the kind of scale you need for your API? Not just anecdotally, but do they have a published service level agreement where they specify exactly what you can expect? What’s your recourse as a customer if they don’t meet those expectations?
• Security: What’s their track record in terms of dealing with the threat landscape? What’s their reputation when it comes to security?

Other things you may want to think about:

• Features: Can include specific feature needs that you may not be getting at your current provider, but also making sure the feature set is well-rounded, that the roadmap includes updates that are relevant to your needs, etc.
• Cost: Obviously a factor in any business decision — consider pricing model as well as total cost, whether it’s easy to understand and independently estimate your cost, whether it’s actually based on your usage or not, etc.
• Support: What are the options for getting support? Is it capped at a specific number of requests per month? Do you have to pay more for extra support?

API Usage and Accessibility

How can API documentation best serve a diverse audience of both technical and non-technical consumers?

Greg: This is very important thing to think about — people want to build things and the coolest thing about the internet is that it enables anyone to be a creator. The more you can do to show that not every API call has to involve writing code, the better. Zapier is a good example, the word API is in their name, but they never talk about APIs outside of that. A lot of other companies have built out components where you don’t have to write the full thing, you can just copy and paste one line of code into your docs.

That’s also the downside: people will do that and think they’re done. APIs should be really easy, you send data out and you get data back, but they often aren’t that easy. The thing that’s exciting is remembering that you can really simplify it and the gradually build layers on top to create a bespoke experience. Every API is very bespoke and that’s why ReadMe as a product is so customizable.

There’s not a one-size-fits-all solution for any API, but it’s not enough to just do docs. You should be showing people clicking around, generating code snippets in their language, giving them API keys when and where they need them, etc.

I don't think there's a one size fits all solution for any API. People used to ask all the time, "Can you just magically have it all work? I don't want to write docs." And I think you really need to do everything, you can't do just docs. Showing people clicking around, generating code snippets in their language, giving them API keys where they need it, things like that are also incredibly important. But I do really think you need both. Maybe AI will come along in two years and that all is moot, but for the next few years, that's my answer.

Josh: It’s worth thinking about if it’s equally easy (or at least equally accessible) for both non-tech and tech audiences in terms of documentation. For a developer using your API, it should feel familiar — it should be consistent with standard naming, formatting, etc. conventions and be consistent with the way similar APIs in your industry operate. This helps it stay intuitive.

Greg: I both agree and disagree with that, although it’s more of a different perspective than actually disagreeing. I’m not necessarily creating the API, I’m creating a tool for APIs. Best practices is an interesting concept — you should follow them, in general. But the way big breakthroughs in developer experience happen is because of people questioning the best practices. Everyone can’t question all best practices all the time, but it’s good to take a few steps back and consider whether the big-picture way you’ve been approaching things is the best way. Don’t let familiarity keep you from thinking critically about your API.

What guidelines do you use for deprecating vs. maintaining old API versions? What’s the best way to smoothly sunset old versions and get users to upgrade?

Greg: I think that's the wrong question — I don’t think you can smoothly sunset something. People have built on it, they’re relying on it (unless there’s a large security breach or something similar). Changing things puts a lot of effort and work on the people who have built on it already.

Instead, I’m in favor of proxying old APIs instead, where you only have one version of the code running, but keep old versions running by proxying and doing mapping behind the scenes to match new names, etc. That way, you never disrupt anything. We’re still using Stripe’s API and built on it initially in 2014, they’ve changed a lot of things since then and it’s never broken, and they’ve never asked us to upgrade or change or rewrite things. That would have been a frustrating user experience if they had.

The best way to do it is to find a way to keep the API (and its current users) running without being beholden to the past. Don’t make your users suffer and rewrite code.

Josh: I agree — ideally, you don’t do this. Changing customer behavior is hard and asking them to do a lot of work to move to your API isn’t a great customer experience. It also creates churn risk; if they have to do the work to switch to your new version, they very well may investigate all of your competitors’ versions as well.

Ideally, when building API, you think through one-way and two-way doors and create the semantics of requests, responses, naming conventions, etc. in a stable, future-proof way. The entire value of an API is as an abstraction layer, where you can improve things and the customer doesn’t have to worry because the API stays the same.

If it’s something you absolutely have to do, you need to communicate transparently. Why are you doing this? When? What do your customers need to do? Give them a really easy way to do it and maybe an incentive for moving over, like plan credits or upgrades if they move by X date. Or do what Greg said and make the changes behind the scenes. Whatever you do, make sure the new version works and scales and have monitoring in place, so you can see when users have moved off and phase out slowly, instead of yanking the rug out from under the users.

What are your biggest pet peeves when it comes to APIs?

Josh: I just mentioned deprecating APIs out from under people, that’s a big pet peeve of mine, but aside from that:

• We’ve also touched on lack of documentation or unclear documentation and how that affects users — that's another one of my pet peeves
• When it’s not clear how to use an API, get registered and set up with it, what a request or response looks like
• No testing environment — it's important to have a sandbox where people can try it and (if monetized) try before they buy
• Inconsistency in naming conventions and semantics

Greg: APIs are supposed to be really simple: you send data, you get data back, maybe an action happens during that time…but every API does things slightly differently. Everything else in tech is getting easier and nicer to use, but APIs still feel exactly the same as they did in the 90s.

People just believe that when they’re creating an API that the confusion and slight differences are the way it has to be, which makes something that should be simple be confusing. I’m really excited for people to care more about developer experience; people will say they do, but then do things because it makes sense for them as the API creator, without thinking about end users.

I’d love to see people take a step back and ask themselves how to simplify it, make it easier. People make their APIs super complex and forget that nobody cares about your API — they care about what cool things they can do with it.

How are customer stories and their ReadMe usage impacting what ReadMe is building next?

Greg: ReadMe is a very different product than it was five years ago, people care more about different things. Before, people just wanted to render an OAS file. Now, people are using their documentation as a marketing tool. We get different feature requests. People are really excited about things like layering realtime logs on top of docs and five years ago that wasn't the mentality.

Five years ago the mentality, and our tagline, was “really nice docs in five minutes.” Now, no one thinks that way. Implementations take months, because people put so much time and effort into it. People want to plan launches around their docs. Teams have gone from 1-2 users to 20-40 people using ReadMe. I’m really excited about current roadmap; it feels like now what we're building and what people want is converging.

What are you most excited about in your 2023 roadmap?

Josh: There's not a lot I can share in this setting, but I can say there are top customer asks for 2023:

• Returning to availability and security, they’re the number one priorities
• Even under the face of rapid growth, constantly raising the bar for uptime and scalability
• Security can be weird to talk about because it's measured by the negative case and the bad things that aren’t happening, but doing well on that front
• Continuing to improve both of those things, along with delivering some new things customers are asking for

Greg: There are lots of exciting things coming up:

• Getting more into internal microservices — not just doing public APIs, but internal APIs as well, which can be just as (if not more) important
• Our goal for this year is to make it so that all of our docs are backed by Git, so you can write and automate the process however you want
• I'm excited about layering GPT-4 on top of the docs, so you can ask questions, which may be a little gimmicky, but is also really fascinating — being able to actually ask it to write code snippets for you, as opposed to having to write them yourself

The last thing I'm really excited about is ReadMe is going to become more of a developer hub, like a developer dashboard. We want to bring it all together and have it all in one spot; lots of upcoming launches around that. Other than that, we're having a conference in San Francisco in May —not a roadmap thing, but watch out for that if you want to see more ReadMe stuff, especially if you're in San Francisco and want to do it in person!

That's all, folks!

We hope you enjoyed reading Greg and Josh’s thoughts — we certainly enjoyed hearing them! If you’d like to read the full transcript, you can do that here. And if you want to learn more about what ReadMe can do for your team, take a look at our customer stories, or sign up for a free trial here.

When it comes to developer experience (DX) at ReadMe, two mantras often come to mind:

1. Awesome by default 🆒 While developers often benefit from having a slew of configuration options and flags available in their tooling, too many options can feel overwhelming, particularly for first-time users. Having a sensible default experience will help your developers get to that first successful API call even faster.
2. Meet users where they are 🤝 No two developers are alike, so your API (and your docs!) should reflect that. Your developers will often have different use cases, different technical stacks, and different levels of experience with APIs. The more your API can accommodate your developers and their diverse needs, the higher your API adoption.

With these in mind, we’re always looking for new ways to make APIs more accessible and lower the on-ramp to getting started. Today, we’re sharing more about api, our open-source SDK generator.

api takes your OpenAPI definition and generates a powerful SDK that’s custom-tailored to your API. With the world-class developer experience that an api SDK provides, making API calls has never felt easier or more magical 🪄

The api origin story 💭

You’ve probably heard a lot about APIs, but what exactly is api and why does it matter?

Let’s start by looking at a typical code sample for an API call. In this example, the sample is written in JavaScript, and it uses the Fetch API to fetch our current job openings from the ReadMe API:

fetch('https://dash.readme.com/api/v1/apply', {
  method: 'GET',
  headers: { accept: 'application/json' },
})
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

ReadMe’s API reference automatically generates code samples for your endpoints in dozens of languages and libraries, including fetch. And for good reason too — fetch is popular, versatile, and it’s available everywhere!

• It’s baked into every modern web browser (including the one you’re likely reading this on!) 🌐
• It can run on the server out-of-the-box (thanks to runtimes like deno and Node.js 18) 📦
• It offers a tremendous amount of flexibility to handle a wide variety of API use cases 💪

But this approach isn't for everybody. Since fetch and other generic HTTP clients are designed to make calls to nearly every API under the sun, there’s inherently going to be verbosity, boilerplate code, and a whole lot of configuration options. This makes your typical, off-the-shelf HTTP client pretty confusing for many API users.

At ReadMe, we’re constantly keeping an eye on the best DX out there, and we’ve come to notice a trend. Many of the top API-first companies out there offer their own custom SDKs, such as Stripe, Twilio, and Plaid (and I’m only linking to their JavaScript SDKs!).

Those companies and their respective SDKs are the tip of the iceberg. API-first companies are continually investing in SDKs for a variety of programming languages, and for good reason. With an SDK that’s custom-tailored to a single API, their users have much less boilerplate code and confusing configuration options to deal with, so they can get to that first successful API call even faster.

Thousands of great APIs run their developer hubs on ReadMe, where our customers are already documenting every little detail about their API using the OpenAPI Specification. This got us thinking: “the OpenAPI Specification already provides a ton of valuable information about an API, what if we use this to generate an SDK that’s as good as Notion’s JavaScript SDK”?

And that, my friends, is how api came to fruition. 🌱

Making fetch api happen 💄

Let’s revisit our previous example: fetching current job openings from the ReadMe API. The fetch sample we looked at works perfectly fine, but what would an API call look like if the ReadMe API had a custom-tailored SDK? That’s where api comes in.

Here’s what the same API call looks like with a code snippet using the api-generated SDK:

readme.getOpenRoles()
  .then(({ data }) => console.log(data))
  .catch(err => console.error(err));

Notice how there is far less boilerplate code than the fetch example, and much of the complexity is abstracted away. But the code sample does the exact same thing!

Let’s break down the process of SDK generation, end to end:

1. The ReadMe API is documented using an OpenAPI definition. Within that definition, there is an operation with an ID (i.e., operationId) called getOpenRoles.
2. Anytime an API user (in this case, someone that wishes to apply for a job at ReadMe) runs the installation command to set up the SDK, api takes the OpenAPI definition and generates an SDK that’s completely customized to the ReadMe API. It contains methods for every operation available in the API definition, as well as detailed descriptions of every request and response parameter.
3. Once the installation is complete, the user imports the SDK into their code and starts writing. Thanks to the comprehensive TypeScript definitions produced by api, code completion platforms like IntelliSense can guide them along as they write their snippet. They’re able to successfully hit the ReadMe API with a code snippet that’s a fraction of the length and complexity of the corresponding fetch snippet.

That’s the developer experience ethos we’re going for with api: a readable, succinct code snippet that will get you to that first successful call in a jiffy. 🥜

Elevate your OpenAPI-powered DX with api 📈

One important design consideration as we built api is that we wanted the SDK generation to be completely agnostic of your documentation platform, much like OpenAPI itself. Because api is built on top of the OpenAPI specification, anybody that describes their API using OpenAPI can step up their DX with a custom SDK generated by api.

There are a few requirements to get started:

• Node.js and npm installed
• A local directory with a package.json file created
• An OpenAPI definition, either located in your directory or served from a URL

Once you have everything in order, you can generate a custom-tailored SDK by running the following command from the root of your directory and following the prompts:

npx api install [path-to-api-definition]

Once the SDK is generated, you’ll be writing succinct code snippets and getting to that successful first API call in no time 🚀

Two birds 🐦, one incredible DX 🌟

If there’s one thing that developers, technical writers, and pretty much anyone enjoys, it’s being able to stretch your work so it goes further and saves you time. And that’s another reason why we’re so excited about api and how it leverages the existing OpenAPI ecosystem to supercharge your users’ developer experience in ReadMe.

Before api came around, there were already many great ways that a comprehensive OpenAPI definition could set your API reference apart and further set your users up for success:

• Comprehensive security scheme definitions can help your users navigate one of the trickiest parts of getting started with an API: authentication!

• Detailed request parameter descriptions and definitions (with default values, enums, and examples!) eliminate ambiguity and help your users understand exactly what data to send to your API:

• By capturing exhaustive response schemas and plenty of examples for every edge case, your users will know exactly what to expect from your API’s responses:

But who said that a great developer experience should start and end with your docs? By investing in the above aspects of your OpenAPI definition, your users’ experience with your api-generated SDK becomes even more magical:

• Thanks to that security scheme definition, passing in authentication credentials into your SDK is a one-liner:

sdk.auth('API_KEY');

• Because of those detailed request parameter definitions, passing in request parameters is a much more straightforward exercise that uses a fraction of the boilerplate code. And thanks to the power of TypeScript, users will get helpful cues about the parameters as they write in their editor:

• And because of those exhaustive response schemas, users will also be able to leverage TypeScript hints to parse out response bodies:

There’s already a tremendous amount of value in putting together a rock-solid OpenAPI definition. With api, you get even more developer experience bang for your OpenAPI buck 💸

Available now in your ReadMe API reference 🦉

If you have an API reference section that’s powered by ReadMe, your users can start writing better API calls with api today. They can select Node in the language selector and select the api library to get started.

If you run into any issues, check out our docs and feel free to contact us at support@readme.io. api is proudly open-source (shoutout to Jon for your all your hard work on this!) so feel free to open up an issue in the api GitHub repository.

At ReadMe, we think a lot about creating a great experience for developers building with our customers’ APIs. But we care a lot about the folks responsible for those APIs, too! Behind the scenes of every developer hub, there’s a team of engineers, product managers, and technical writers who make the magic happen ✨

Today, we’re excited to kick off our first “Behind the Docs" user Q&A — giving you a closer look not just at how they’re using ReadMe, but at their career learnings, perspective on working with APIs, and favorite growth resources.

First up? Beth Favini, Senior Director of Product Documentation at Couchbase. We worked closely with Beth during her time at Akamai as Senior Director of UX Technical Writing and Learning, and she recently took on this exciting new role to scale the documentation team at Couchbase. Below, she shares her insights on breaking into technical writing, becoming a leader, and what keeps her motivated as an industry vet in the growing field of technical writing.

Let’s talk about your career path. How did you get into technical writing?

In college, I majored in English and had always intended on becoming an English teacher. But after about two days in the classroom, I realized that was not for me. After that, I pivoted and altered my major, adding a specialization in professional writing. I studied technical writing, then I got an internship and started my career as a technical writer.

Early in my career, I was really intimidated by all of the smart technical people around me that had a more technical background than I did.  As a result, I was afraid to ask questions when I didn’t understand something., But then one day, I was at a product design review and I realized that what everyone was talking about didn’t make sense to me. At first, I was afraid to say anything because I assumed it was me — that I just wasn't getting it. But finally, I realized I wasn't going to be able to do my job if I didn't ask the question. I forget exactly what it was, but  I seem to recall they were discussing a feature with a requirement that wouldn’t be supported in the new release. The logic didn't add up. So I said, “I don't understand. How do we reconcile that?” And the room was silent for a minute and I thought, “Oh no, they're going to fire me. They found me out.”

Then the leader turned and said, "Oh wow, that is a good question. We didn't think about that." And they had to start over. Over time, I became more confident and would ask questions when things didn't make sense to me. The aha moment for me was that I had always assumed that I didn’t have a technical mind because I was an English major. I liked writing. I was not a math person. But what I learned from working in tech was that I had a very analytical mind and the questions I asked added value.

Learning that helped me gain confidence and grow in my career. I try to share that with young people who are just starting out, because being a technical writer is not one size fits all. You can come from a variety of backgrounds and still add a lot of value and have a really great career. The more I asked, the better I did. It really helped me rise in my career, the fact that I wasn't afraid to ask questions and they were generally really good ones.

What drew you to your role at Akamai? The company, the position, the team?

A bit of all three, but I think the big draw was that I was finally going to be working within a User Experience team. For my whole career, I'd been doing UX work, but I was never part of the actual official department. Akamai was the first opportunity I had to be one of the pillars of UX. They have three pillars now, but at the time, the pillars were UX research, UX strategy, UX design, and UX writing. So I came on board as a director of UX writing and joined this UX team and feel like I learned so much about UX processes. I had always operated using common sense and having empathy for the user, but I learned a lot about UX best practices and how to design things properly based on research, data, and insights.

And how did you grow from technical writer to where you are now, leading a team?

That was a little bit of a windy path too, because I never wanted to be a manager.
When I finally did take a management position, I found it to be really challenging and stressful, and went back to being an individual contributor, which I loved. But at that point, I missed the collaborative dynamic I had with other managers and having more of a voice in decision making. So, over the course of the next seven years or so, I went back and forth between management and writing. I wasn’t really sure which I wanted to pursue.

In the end I settled on management, and now I've been managing teams, large teams even, for about 20 years. I find it really rewarding. I learn new things all the time. It's never boring — sometimes it's really hard. I feel like I’ve found my sweet spot, and Akamai allowed me to rise to a level I had never been before, along with giving me a role in UX. I loved the variety in my job there, but it was certainly been a zig-zaggy road to get there.

How has managing people changed your perspective on work?

First, I find it really rewarding to help people find their strengths and to use the strengths of people to get something done. I’ve had several interns whom I mentored that have now surpassed me in their careers. I love to see their success! It was great passing what I knew on to them and helping them thrive. I found that very rewarding.

Secondly, managing people means I can make a bigger impact with a team than I could all by myself. And it's been wonderful, especially this transition to ReadMe. During the migration over to ReadMe, we did so many customizations. We had to work with your team, my IT team, and Akamai's InfoSec team. It really wasn’t an easy project at all, but when I think about how it all came together and how everybody contributed their own special superpower to the project, I'm so proud of the results. I find it really rewarding, and I never could do that if I weren't in the position I was in. I was able to influence a lot because of my position and it ended up yielding great results. Not because I did everything myself, but because I was able to get a team to work together.

Do you have any advice for people who are looking for similar technical writing roles?

The biggest piece of advice that I’d give to someone is first of all, don't think that because you're an English major, you're not a technical person, to go back to that for a minute. Aside from that, if someone wanted to go into technical writing, especially at this point in the evolution of high tech, I'd say, get some API skills. Become knowledgeable about Git and DevOps and APIs, because that's really the future. Gone are the days where you could just describe a workflow on a UI. People really need to have API writing skills, so I would encourage that.

If you want to get into UX, I would say read up on some of these proven processes and become a little bit more educated in UX than I was. I stumbled into it. But I think if you wanted to pursue a job in UX or UI writing, there's a lot of ways that you can prepare yourself better than I did.

What drew you to this new position at Couchbase?

The position at Couchbase appeals to me because it gives me chance to once again work in the database space — I led the doc team at Vertica for several years before joining Akamai. It also allows me to join a smaller company at an earlier stage of growth and help the documentation team scale with the business. I feel good about what we accomplished and where things stand at Akamai, and felt it was time for a new challenge.

Any favorite resources for learning about technical writing?

Here are a few of my favorites:

• Tom Johnson’s API Documentation course, in his I’d Rather Be Writing blog
• Docs for Developers, a collaboration between doc leads at Splunk, Google, and Microsoft
• API The Docs writing community, which provides resources and conferences that support API writers everywhere — along with their podcast!

Thanks, Beth!

We're excited to hear more about the exciting developments at Couchbase as Beth gets started in her new role, and you can learn more about her developer experience transformation at Akamai in their customer story. Stay tuned for the next Behind the Docs!