From high school entrepreneur to his current position, Josue has been working in tech for most of his life. As a Senior Principal Product Solutions Architect in the R&D organization at OneTrust, his first priority after being hired was to improve their APIs and developer experience.
In addition to finding a vendor for their API documentation, he acts like something of a product manager for their DX, working closely with technical writers, product managers, and developers. Keep reading for his insights on developer experience, cross-functional teams, workflow automation, and more:
How did you find yourself in your current role? Have you always worked in tech-related roles?
To really summarize it, once I found my niche, it's been following my manager. I've had the same boss since I graduated college. But getting to that point was a story within itself — I grew up on the southside of Atlanta, and I was in the first generation of my family to go to an American college. When I was in high school, I didn’t know what I’d want to major in. At the same time, when I was 15, I started getting into computers and computer repair, where me and my best friend started an IT consulting business. Think of Geek Squad, just the startup version with two little high school kids.
I always had the hustler mentality, and a technical knack for solving problems. That's the common theme throughout my career. I can quickly understand how something works, and I always had a curiosity for how things work. I’d get bored in class, stare at the ceiling, and start wondering how the water gets activated after a fire alarm. And then I’d go and research that.
When I started my business and translated that curiosity into technology, it was really just break/fix. We worked with a lot of nonprofits, and did that all throughout college. I also had a couple of odd jobs through college, working in IT roles. I learned that I really loved helping customers, because you get the immediate gratification of, "Wow, you're so smart, you fixed that for me," and I also get paid.
In high school, when I was Googling what major to do, I figured that I know computers, and computer engineering pays well, so that’s what I’d major in. In my junior year in college, I realized I didn’t really want to do that at all. Computer engineering actually involves designing microprocessors, that sort of thing — you're going to be working in a research lab and not really talking to people. It was too late to switch, so I just buckled down to finish it. I took 21 credit hours both semesters my senior year, while also working three jobs, so I could get out as quickly as possible. I got 13 job offers ranging from consulting work to getting recruited by the CIA to a startup. The startup where I ended up going was where my best friend interviewed last minute, and I was like, "Whoa, that salary is $20,000 more than any of my other job offers."
That job seemed like the best of both worlds — I could follow the money and stay close to him. So I went to that startup, AirWatch, and that’s what led me into APIs. My first week of technical training was done by my current boss, and his training style wasn't textbook training. He essentially gave us access to a lab and said, “You're going to stand up all this infrastructure that a company has, active directory, exchange, certificate services. Just stand it up, do your YouTube research, figure it out, get it up and running, and integrate it all. Then, integrate it with our product.”
It took us a while to learn that way, but then, once we were done, we showed him. Then he told us to delete all of our work and do it again. The second time around was faster because we didn’t have to do as much research. And every time we did it, we learned something new, because something else would go wrong. That gave us the foundational knowledge that really helped us help other people at the company when something broke. We had seen the errors before and knew how to fix them.
Throughout my entire career of helping people, answering questions, and creating documentation, it's all been focused around, how does it work? If I can teach you how something works, I don't have to teach you the individual error codes and what they mean. Like I said, it’s break/fix. If you can teach someone how something works, they’re so much more able to troubleshoot it themselves, understand where it broke and what broke, and figure out how to fix it.
All of my roles, from pre-sales to post-sales to technical enablement and everything else I’ve done, have always focused on that. Don't answer the question directly, because when you answer someone's question directly, you're just teaching them to ask you the next question. Any time I answer a question, I try to provide all the context and background, explain how it works and give them the tools to troubleshoot for themselves, instead of just answering someone's question.
What first piqued your interest in APIs and/or developer experience?
When I was going through that ramp-up period at my first job, the troubleshooting aspect allowed me to go into network inspection, where you go into the browser and you look at all the network traffic. That was me playing around with APIs without me knowing that I played around with API.
I was heavily leveraging APIs for a good five years before I ever knew what an API actually was. I never set foot into a developer portal to look at APIs. I understood APIs very well by then — I just referred to it as network traffic, network requests, application requests, whatever you call it. For me, it was like, "Wow, there's the UI, but then, I can look at the network traffic and literally see all the data that's coming back and forth." It gave me my Matrix sunglasses, where you put them on and can see all the code. That's really what caught my interest.
Once I actually learned what APIs were and that they were documented, and started using developer portals, I was like, "Wow, this sucks. This is completely inaccurate." There's way more information when you're leveraging APIs live, integrated into a system, to see how the developer strung everything together, rather than just looking at documentation. That's why I don't really use developer portals. I literally just jump into the product. I open it up and look at how the APIs are being leveraged to have a better understanding of APIs in general. Having that background really showed me how critical it is to have accurate, up-to-date documentation.
What’s the first thing you think of when you’re thinking about developer experience and how to create a good one?
For me, the best north star of developer experience is having a developer portal that’s completely self-service. There’s no need to reach out to support, because nothing went wrong. The documentation doesn’t leave a developer with additional questions. Regardless of where they land, whether it's a page, a recipe, a code sample, or an article, there’s the information on the page and there’s also links to other content to send them to the right place for what they need.
This is where accuracy comes in — it has to be completely accurate, because if it's not accurate, it's not going to be completely self-service. To summarize it all, my goal is for the published documentation to allow a consumer, whether they're a developer or not, to answer all of their questions.
This is one place where Recipes can play a big role and save users time, because it’s a common use case and there's an explanation of how to use it. What are the best practices? What are the roadblocks to watch out for? You can copy the skeleton code, it gives you a good place to get started, and now, you can modify it to your needs. It’s a good way to implement that “teach by example” troubleshooting philosophy.
How do you approach team workflows around API documentation?
That’s a great question. I do think that in general it’s good to keep the vendors and tools that you use separate from that discussion, in that you shouldn’t expect those vendors or tools to build the workflow for you. I’m a huge proponent of picking the best developer portal vendor possible, instead of looking for something that does everything. A lot of organizations will look for an API documentation tool that can do linting, API governance — literally everything related to APIs. That tool might check all the boxes, but it’s not a master of any one of those things.
The way I see it, you should pick the best solution for the most important task. The most important task, for me, is what’s customer-facing. Everything else internally can look like spaghetti code. It can look like a MacGyver invention from a bunch of open source tools, as long as it works for our internal teams.
The most important aspect internally is going to be the least technical person, the tech writer. The tech writer's requirements are often similar to the customer's requirements — a nice interface. Their most important feature is an easy-to-use rich text editor interface that makes it easy to write the documentation. Everything else before that is going to be generated from an Open API specification or an API file, and how that file gets generated doesn't really matter to the developer. It doesn't really matter to anyone, as long as there's an automated workflow that works with the internal processes that exist today.
When a developer is developing code, all they have to do is annotate their code, and we have a library that will automatically generate the API specification. Then, there are Jenkins workflows, pipelines that take that specification through an approval process. Once it gets approved, it automatically gets published onto the developer portal.
There's a full process built in on the backend. It works for everyone, but everyone doesn't know all the steps of the process. They’re only aware of the normal day-to-day processes they do, and then they get pulled in during approval processes, but the entire process is automated.
It’s a very modular system, as well, which makes it more flexible in the long run. If we want to add something — linting, for example — I can go to OpenAPI.tools and find a tool that covers that stage of the process. I’ll find a vendor that’s open source and CLI, and just build that into the workflow. Then, before our developers try to publish changes, they get real-time feedback that something they wrote doesn’t follow our standard, before it ever gets to architecture approval or tech writing approvals.
My approach is to build in automation that makes it easy for the people involved in the process to self-service themselves, before the automation takes over and moves it downstream. I want to meet our team members where they’re at, while also making sure they have the knowledge and tools available to troubleshoot things on their own.
One challenge you’ve had to address with your API documentation is the different levels of technical knowledge among both internal and external users. How do you handle that?
When I first joined OneTrust, I came from a mobile device management company where the user persona was always the same. There were different variations of IT admins that we dealt with, but at the end of the day, all of our users were sysadmins. Here, we have so many different modules and product sets, with a variety of user personas, which also holds true when you look at the developers and contractors involved, and what kind of developer experience they’re looking for.
For example, I quickly learned that not all of the developers using our developer portal were full-time programmers. Some of them are scripters, programmers, or web developers, but some work in cybersecurity, data privacy, legal and compliance, or digital marketing.
One specific example is we see the title “Risk Analyst” a lot. Anyone who deals with the privacy sector is in our developer portal looking at our APIs, because OneTrust has a product that does workflow automation via internal APIs or API-powered internal products. All of these traditionally “non-technical” folks are looking at the developer portal to get all of the data — incoming and outgoing — so they can then go to the integration manager and string those APIs together in our workflow engine.
This also came up when we were onboarding our technical writers and getting them up to speed so they had the necessary background to properly document our APIs. It was a huge learning experience for me. I discovered that it’s really easy to make a lot of assumptions about the person reading the documentation and what they might or might not know. But, yes, we definitely aim to cater to everyone ranging from the non-technical to the very technical by providing as many resources as possible to help people troubleshoot on their own.
What’s been the biggest surprise through that process, as you’ve learned more about your documentation/portal users?
The most shocking thing I’ve come across — and it happens all the time — is the amount of contractors using our developer portal. Often, a OneTrust customer contracts a developer to do an integration, and doesn’t give them console access, so they’re essentially told, “Here's your client credentials, here’s the API developer portal. Now, go build this for us.”
That’s not how I work at all. I, personally, almost never use documentation. I like to experience APIs and how the product uses the APIs, and that’s how I learn how APIs work. So this was an entirely new experience I’d never thought about. I would ask, “Wait, so you don’t have access to the console?” And they’d say, “No, I’m just a contractor. They didn’t give me any admin access to the console. So I solely rely on your documentation to build out these integrations, and if the documentation isn’t right, the integration doesn’t work.”
As someone who rarely uses documentation myself, that really opened my eyes to the importance of making the most accurate documentation possible. Now, our specifications are generated from our code, so there’s no human error aspect to it.
What are your metrics for API success?
We do look at net new users, year over year, and we like to see that on an upward trajectory. But I wouldn’t say that’s how I define success. A successful developer experience, in my opinion, is really just a truly hands-off experience where a developer can:
- Be tasked with integrating with our product
- Go to the developer portal
- Completely self-service themselves
…all without encountering errors in the docs that keep them from finishing their project.
With that in mind, one of my success metrics is actually a negative metric: seeing how many 400 errors we’re getting and which API endpoints are getting those errors. A 400 error is indicative of a bad request, which means our documentation was so unhelpful that the user wasn’t able to decide what to put in the payload, and got a 400 error as a result. If there are multiple 400 errors, that means the user is just guessing at random. Either they’re not looking at the documentation at all, or they’re looking at it and still having these issues calling that API.
When I see that, it’s a massive red flag, and I go back to the drawing board to figure out what’s going wrong. Where could we have gone wrong with the documentation? How can we make this more simple for a technical or non-technical user to be able to leverage this API without producing a 400 error?
Roger Deane, our Senior Director of Product Solution Architecture and Technical Writing, his philosophy is that every user should be able to find everything they need — the values required, whether query or body parameters, what type they are, if certain values are required — without having to talk to someone on our team. If we’re getting questions about how to make an API work, our documentation isn’t doing its job.
Do you have any favorite resources to share, or things you’re excited about right now?
I mentioned OpenAPI.tools, which is a really useful site that has a bunch of vendors (both open source and not) for every stage of working with APIs. Whether you need SDK generation, governance, API testing, linting, or something else, you can find it there. It’s one of my favorite resources.
I also recently joined a webinar from the OpenAPI Initiative, where they were talking about the Arazzo specification, which is OpenAPI specs, but for workflows. Think of ReadMe’s Recipes, where you can string together APIs for a business objective, so our customers can use that sample code.
The Arazzo specification is something I’m excited about, and I’m really excited to see everyone that has a workflow engine use it — whether it’s OneTrust Integrations, Microsoft Power Automate, or any of those other vendors that let you import an OpenAPI specification and then use a canvas to plug and play. All of those tools are proprietary, so you can’t import and export between them.
I’d love to see companies working in the API space adopt this specification, so people can build these workflows and then let customers take them to plug into their business tool of choice. It’s a really hot topic right now and I’m really excited for it.
A comprehensive developer portal is core to offering a great developer experience for your API users. If you're looking to get started or learn more about ReadMe, you can reach out here to get a demo or head here to sign up for a free trial.
