Hi! I’m Raleigh, and I lead the Engineering team here at Stoplight. Some of you may recognize from previous engineering excellence blogs on release schedules and predictability metrics. But did you know that I was once a happy, paying Stoplight customer? I obviously may have a bit of a biased perspective here, but I wanted to share my journey with you in case it answers questions and creates clarity for other program leaders.
Our crack marketing team (gratuitous plug, so they boost me on social, naturally) asked if I could share my “Why Stoplight” viewpoint and, ultimately, give you a view into the benefits of the Stoplight Platform for those who – like me at the time – were looking to solve a different problem then just the “design-first” work that caters to the enterprise level. Because, let’s face it, some of us smaller companies are just seeking a good tool that will save time and make our lives a little easier.
My Stoplight customer story begins when I was working at Medici as the Director of Engineering. Our product was a telehealth platform, which consisted of two mobile apps; a web app, and an API application.
My Problem: No Consolidated Docs
The team that preceded me operated in a code-first approach, meaning individual developers coded APIs before sharing and/or documenting them. This led to documentation spread across multiple tools, aka a big headache for me. As I recall, there were several recognizable names in the mix: Apiary, Postman, and Swagger. Often, the only documentation available was a Postman collection curated by the QA team for release testing. In other circumstances, there was documentation in multiple locations, but most often it was incomplete or out of date, or both.
As a new team coming in, we needed to understand what we had and how to use it. Additionally, we needed to find ways to ensure that we weren’t rebuilding something that already existed. I needed a tool that consolidated the API catalog documentation into a searchable, single source of truth (ahem–Stoplight did the trick). Better, integrated, visible docs–check!
My Other Problem: High Engineering Turn Over 🙁
When I started, there had been a large amount of turnover on the Engineering team and it had been months since the last new feature had been released. I needed to rebuild the team and shorten the learning curves for the new hires. To this end, I needed a single, searchable catalog of the APIs available to us so that we wouldn’t rebuild something that already existed.
We evaluated several tools but settled on Stoplight because it solved the main need to provide a single catalog of APIs that made training my new engineers simple and quick.
And My Bonus Problem: Nobody Likes YAML
Look, as I stated above, I needed to save as much time as possible and get my new team of developers trained up effectively and quickly. Stoplight was the only tool we were assessing where there was the added bonus of a form-based API designer. My team had enough new things to learn, and I was ecstatic about providing a solution that ended with hand-writing YAML or JSON spec files!
Sure, we could annotate code to auto-generate API docs, but that wasn’t ideal for feature delivery within a server / multi-client application. The best thing to do was define the contract up front, enable the resource with the mock server, and allow the client developers to start work as soon as possible. Sounds like design-first, huh?
Additionally, the pain of writing YAML files was a cognitive load that we did not need (I’m not just speaking for myself here). There was enough complexity in learning all the languages and new system architectures as it was. Using a form-based approach lifted some of the weight off, enabling us to focus our brain power and energy on design, technology, and delivery.
The Other Cool Things That I Didn’t Need But Found Anyways
In addition to the form-based editing and ending of YAML right then and there were a few side benefits that I welcomed, even if it wasn’t the problem I was seeking to solve at the time.
- Mock server, enabling concurrent client / server-side development, which shortened feature delivery cycles.
- Easy API Design-First Strategies.
In the end, finding the solution that was the best fit for our team truly depended on our use case and where our organization was at the time. As a leader, you must decide what’s most critical for your team to succeed, noting that starting small is still a start.
Make sure you listen to your developers and their pain points and try your best to match it up with a tool that solves those pain points. For me, during my time at Medici, improving developer experience with a form-based editor/single API catalog and getting our docs on the same page made a world of difference in our productivity and in reaching our organizational goals.
ANYWAYS, obviously, I liked Stoplight so much that I ended up joining the company not long after (what can I say, I’m a sucker for a good product and a good team). Now that I’m on the inside, I’m always looking for ways our team can improve and create the best possible product. If you have ideas, I’m all ears–drop them in our Product Roadmap request submissions, and I will check them out!
And if you’re like me and want to join a team of design-first rockstars, head over to our career page to see our open roles.
PS: If you’re also looking for a tool that empowers design-first development, Stoplight also excels at that (though that wasn’t my primary need). I first came across the term ‘design-first’, from working with our now CTO, Jason Harmon, at uShip over a decade ago. In an API design-first development process, “we begin with writing a specification and engaging all stakeholders in the process from its inception. The result of a design-first process is an API product that is comprehensive, consistent, and understandable by both collaborators and machines.”
