Tips for Transforming the Developer Ecosystem

Building an API that empowers developers and fosters a thriving ecosystem around your product takes intentionality. Here are 11 guiding principles to design and create robust APIs: 1. 𝗦𝘁𝗮𝗿𝘁 𝘄𝗶𝘁𝗵 𝘁𝗵𝗲 𝗨𝘀𝗲𝗿:  Identify your target developers and understand their needs. What tasks will they be using the API for? Design with their experience in mind. 2. 𝗖𝗹𝗲𝗮𝗿 𝗮𝗻𝗱 𝗖𝗼𝗻𝗰𝗶𝘀𝗲 𝗗𝗲𝘀𝗶𝗴𝗻:  Strive for simplicity and consistency in your API's design. Use well-defined resources, intuitive naming conventions, and a consistent HTTP verb usage (GET, POST, PUT, DELETE). 3. 𝗩𝗲𝗿𝘀𝗶𝗼𝗻𝗶𝗻𝗴:  Plan for future changes with a well-defined versioning strategy. This allows developers to adapt to updates smoothly and prevents breaking changes. 4. 𝗗𝗲𝘁𝗮𝗶𝗹𝗲𝗱 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻: Invest in comprehensive and up-to-date documentation. Include clear explanations of endpoints, request/response formats, error codes, and example usage. 5. 𝗘𝗿𝗿𝗼𝗿 𝗛𝗮𝗻𝗱𝗹𝗶𝗻𝗴:  Implement a robust error handling system. Provide informative error messages with clear explanations and HTTP status codes for easy debugging. 6. 𝗥𝗮𝘁𝗲 𝗟𝗶𝗺𝗶𝘁𝗶𝗻𝗴 𝗮𝗻𝗱 𝗦𝗲𝗰𝘂𝗿𝗶𝘁𝘆:  Protect your API from abuse and ensure data security. Implement rate limiting to prevent overwhelming your servers and enforce strong authentication and authorization mechanisms. 7. 𝗧𝗲𝘀𝘁𝗶𝗻𝗴 𝗶𝘀 𝗖𝗿𝘂𝗰𝗶𝗮𝗹:  Thoroughly test your API before exposing it to developers. Use unit testing, integration testing, and automated testing tools to ensure functionality and reliability. 8. 𝗣𝗲𝗿𝗳𝗼𝗿𝗺𝗮𝗻𝗰𝗲 𝗢𝗽𝘁𝗶𝗺𝗶𝘇𝗮𝘁𝗶𝗼𝗻:  Focus on optimizing API performance. Implement caching mechanisms, minimize data transfer sizes, and choose efficient data formats (JSON, XML). 9. 𝗔𝗻𝗮𝗹𝘆𝘁𝗶𝗰𝘀 𝗮𝗻𝗱 𝗠𝗼𝗻𝗶𝘁𝗼𝗿𝗶𝗻𝗴:  Track API usage and gather insights into developer behavior. Analyze data to identify areas for improvement and potential new features. 10. 𝗖𝗼𝗺𝗺𝘂𝗻𝗶𝘁𝘆 𝗘𝗻𝗴𝗮𝗴𝗲𝗺𝗲𝗻𝘁:  Foster a developer community around your API. Provide forums, discussions, and clear communication channels for feedback and support. 11. 𝗘𝘃𝗼𝗹𝘂𝘁𝗶𝗼𝗻 𝗮𝗻𝗱 𝗜𝗺𝗽𝗿𝗼𝘃𝗲𝗺𝗲𝗻𝘁:  APIs are not static. Be prepared to iterate and evolve based on developer feedback and changing needs. Continuously improve your API to enhance its usefulness. By following these principles, you can design APIs that are not just functional, but also a joy to use for developers, ultimately leading to a more successful product and ecosystem. Have I overlooked anything? Please share your thoughts—your insights are priceless to me.

Developers don't read your documentation. They gut it for parts. If you don't accept this, you'll spend the rest of your career writing for an audience that doesn't exist. Think about it. No developer reads a getting-started guide from top to bottom like a novel. They land on your page with a problem to solve. They scan for a headline, find a code block, and copy-paste it into their IDE. If that snippet is broken, outdated, or throws an error... they don't file a bug report. They leave. And they probably won't be back. The best developer docs in 2025 aren't a library; they're an interactive playground. It's no longer about static pages of text. It's about creating a live, hands-on environment. This means: → Live API explorers that let devs make real calls without leaving the browser. → Editable code samples that run, compile, and show output directly on the page. → Personalized journeys that show Node.js examples to Node devs and Python examples to Python devs. → AI assistants trained on your docs that can answer questions or debug code in plain English. When your docs become a playground, you stop just explaining the product. You start onboarding developers in minutes, not days. You reduce their time-to-first-API-call from an hour to 30 seconds. You don't just create a reference manual; you build the single best sales tool your company has for winning over a technical audience. The old way was treating docs as a reference. The new way is treating docs as the real user interface for your platform. So, for all the tech writers and doc managers in the trenches: What's one interactive feature you WISH you could add to your developer docs right now? Let's hear it in the comments.

Internal developer portals (e.g. Backstage from Spotify, Cortex, Port IO, OpsLevel) are designed to be the single source of truth for services, documentation, and workflows. Yet, many organizations launch portals that end up as underused, confusing tools rather than powerful assets. The issue? Too many companies treat these portals as one-off projects instead of evolving products. A truly effective portal should: ☑️ Streamline Workflows – Make it effortless for developers to find what they need and reduce friction. ☑️ Solve Real Problems – Focus on addressing the actual pain points of your team, not just listing every service available. ☑️ Evolve with Feedback – Continuously iterate based on developer input so it remains relevant and valuable. In my experience—and from what I’ve observed across the industry—shifting to a product-first mindset for your portal can transform it from a static catalog into an indispensable tool that truly empowers your team. What’s one feature or strategy you’ve seen that turned a developer portal from “meh” to must-have? #developerexperience #backstage #devtools

When you're building and improving developer experience, especially in an AI product, practice the "blank slate" technique to make empathy for your users concrete. At least once per quarter, take a fresh look at your docs, SDKs, sample apps, and other educational materials as if you've never heard of the product, have no idea what it does, and no absolutely nothing about how to build with it. How quickly can you start building when pairing only your reasoning and intuition with the provided materials? Now, cut that time down to 5 minutes. How far could you get? What emotion do you feel at the end of that 5 minutes? Do you feel frustrated, frazzled, overwhelmed, or confused? So do your users. Too often we have too much context loaded in our "internal RAM" when thinking about the average developer's journey through a product. Yes, quantitative data in analytics and qualitative data through user feedback are crucial, but you often need to do this yourself to reset and realign your priorities. This is even more critical when building AI products and tools, where the average knowledge of a developer is all over the map. Have you tried this technique before? Any other lessons in empathy in DX you'd like to share?

𝐌𝐚𝐧 𝐩𝐫𝐨𝐩𝐨𝐬𝐞𝐬, 𝐆𝐨𝐝 𝐝𝐢𝐬𝐩𝐨𝐬𝐞𝐬 ⚡️ Platform developers can make plans, but Platform Users determine how things with turn out. A platform can be super-optimised and feature-rich but ultimately fail if it doesn’t get adopted—as good as any other inert product. 🎯 𝐇𝐨𝐰 𝐝𝐨 𝐁𝐞𝐬𝐭-𝐢𝐧-𝐂𝐥𝐚𝐬𝐬 𝐃𝐚𝐭𝐚 𝐏𝐥𝐚𝐭𝐟𝐨𝐫𝐦𝐬 𝐒𝐭𝐫𝐚𝐭𝐞𝐠𝐢𝐬𝐞 𝐀𝐝𝐨𝐩𝐭𝐢𝐨𝐧? Here are a couple of recommendations from our Chief Architect to get this going. 🔦 𝐋𝐢𝐠𝐡𝐭 𝐮𝐩 𝐭𝐡𝐞 𝐞𝐱𝐩𝐞𝐫𝐢𝐞𝐧𝐜𝐞 𝐩𝐚𝐭𝐡 ------------------------------------- 1. 𝘋𝘦𝘴𝘪𝘨𝘯 𝘯𝘰𝘵 𝘫𝘶𝘴𝘵 𝘵𝘩𝘦 𝘱𝘭𝘢𝘵𝘧𝘰𝘳𝘮, 𝘣𝘶𝘵 𝘢𝘭𝘴𝘰... Approaches and frameworks to use your platform. This could be in the shape of approach templates like Kanban & Agile on JIRA or Data Products on DataOS 2. 𝘊𝘳𝘦𝘢𝘵𝘦 𝘌𝘹𝘱𝘦𝘳𝘪𝘦𝘯𝘤𝘦/𝘑𝘰𝘶𝘳𝘯𝘦𝘺-𝘉𝘢𝘴𝘦𝘥 𝘋𝘰𝘤𝘶𝘮𝘦𝘯𝘵𝘢𝘵𝘪𝘰𝘯. The user doesn’t want to learn a new ecosystem unless they have comfortably penetrated into it enough to see one layer of value. 3. 𝘎𝘪𝘷𝘦 𝘢 𝘧𝘭𝘢𝘷𝘰𝘶𝘳 𝘰𝘧 𝘞𝘩𝘢𝘵’𝘴 𝘐𝘯 𝘐𝘵 𝘍𝘰𝘳 𝘛𝘏𝘌𝘔 (𝘞𝘐𝘐𝘍𝘛), 𝘢𝘬𝘢, 𝘵𝘩𝘦 𝘜𝘴𝘦𝘳 My mind, as a user of any product/process, naturally resists new habits. I want to know what I’m getting into first. This could be done in several ways, such as guides on platform IDEs, interfaces, and other toolkit. 💉 𝐏𝐞𝐧𝐞𝐭𝐫𝐚𝐭𝐢𝐧𝐠 𝐢𝐧𝐭𝐨 𝐞𝐱𝐢𝐬𝐭𝐢𝐧𝐠 𝐡𝐚𝐛𝐢𝐭𝐬 ------------------------------------- 1. 𝘒𝘦𝘦𝘱 𝘪𝘵 𝘧𝘢𝘮𝘪𝘭𝘪𝘢𝘳 This doesn't mean duplicating your user's tools/platforms, but rather to be inspired by their day-to-day working frameworks. How often do they jump tools? Is that easier for them compared to a unified self-service layer? What's the semantic convention they can just skim with the lowest friction? 2. 𝘌𝘹𝘵𝘦𝘯𝘥 𝘵𝘰 𝘯𝘢𝘵𝘪𝘷𝘦 𝘦𝘯𝘷𝘪𝘳𝘰𝘯𝘮𝘦𝘯𝘵 In any real-world scenario, your platform is, after all, like a new colleague to all other entities in the data stack. How quickly can it accommodate, adapt, and scale to a position where it enables others? For a deeper dive into these points and more, access this brief and breezy piece by Travis Thompson 🥷🏻 here: https://lnkd.in/dTXjtg44 #dataengineering #dataplatforms