Note: This is an edited and condensed transcript of the podcast and will differ slightly from the original recording.

Interviewer (Sid Maestre): Welcome to the Podcast. Phil, why don’t you tell us a little bit about yourself and what you’re currently working on?

Phil Leggetter: Hi there! I’m Phil Leggeter, and I’m the head of developer experience at Tigris Data, a new company at seed stage.

As the head of developer experience, my role is to be a stakeholder in the hands-on experience of the SDKs and maintain documentation. I also enable the rest of the company to create great docs through guidance and reviews. However, a big part of my job is to help us achieve our goals to get Series A funding. In this smaller developer-focused company, developer experience is the umbrella for marketing.

Developer experience can be a wide span in different companies, but at Tigris, we focus on crafting the APIs and having consistent patterns that help developers use our product or API better. It’s important to have API standards, adopt OS3, and generate documentation and tooling for both ourselves and our customers. Our open tooling allows customers to control their sandbox as they like. Having spent a lot of time in the API community, I felt it was really important for building a good product.

Interviewer (Sid Maestre): How do you define developer experience and what does it include, given that it’s a term that has been around for a while but is gaining more momentum?

Phil Leggetter:  At Vonage, we took a holistic approach to developer experience. As a team of over 40 people, we were responsible for all touch points on the Vonage API platform, from community work to the hands-on experience, including signup flows, the dashboard, and tooling. However, we didn’t handle paid advertising or support teams. When it comes to defining developer experience, there are two levels to consider. The higher level includes every touch point a developer has with your company, while the lower level involves specifics like documentation, API standards, and SDKs. Even tasks like email nurture campaigns can fall under developer experience if the goal is to activate developers. Ultimately, creating a great developer experience involves both levels.

Interviewer (Sid Maestre): Can you explain how the upper level of developer experience impacts engagement through social media and email content, which are often delegated to the marketing team but still crucial for the overall developer experience?

Phil Leggetter: At some of the best companies I’ve worked at, the DevRel team is constantly questioning and refining the developer experience. They live and breathe the developer community. As Mary Thengvall put it, “To the community, I represent the company. To the company, I represent the community.” The DevRel team can provide guidance on what developers think, and ideally, more people across the organization have that knowledge too. But the DevRel team is always a great resource.

Interviewer (Sid Maestre): What does good documentation mean to you in the context of developer experience?

Phil Leggetter: I believe that good documentation is crucial for developer-focused tools, as without it, the product cannot be used at all. Good documentation is a suite of pieces that offer the full set of documentation. It includes quick starts, conceptual documentation, guides, tutorials, open API specs, and fully documented SDKs with inline documentation. Good documentation should also have IntelliSense or autocomplete functionality for developers. It’s the minimum requirement for good documentation

Interviewer (Sid Maestre): Can you share your thoughts on documentation, including the need for conceptual explanations, prioritizing walkthrough guides, and the importance of a user-friendly layout with easy search functionality?

Phil Leggetter: In addition to having good documentation content, the documentation platform also needs to have clear information architecture and search functionality. However, some developers may still prefer to search for information outside of the platform, even if the search functionality is available.

Interviewer (Sid Maestre): The frustration of not finding what you’re looking for in documentation is a common experience. In terms of tools for building documentation, What recommendations do you have on current or future tools for building documentation.

Phil Leggetter: For Pusher, we used Ruby on Rails with a markdown processor for the website and documentation. At Blade Runner JS, we used Jekyll for both website and docs. At Nexmo, we built our own platform in Ruby on Rails. True.ID was built from scratch using Next.js. At Posthog, we used Gatsby for website and docs, and at Ably, we’re moving to Gatsby from a custom-built Ruby on Rails application. At Tigris, we’re using DocuSaurus, which has been great. If I had a choice and the resource, I would still roll my own. Tigris made the right decision to go with DocuSaurus to start with, but ultimately, it’s markdown files that can be moved to something else in the future.

Interviewer (Sid Maestre): I find it interesting that at APIMatic, we have a UI and dashboard for editing markdown files and creating pages for our developer portal. However, the API specific docs are all generated from specifications. Although they talk about docs as code and checking in changes to repos, we use both APIMatic and DocuSaurus for different types of documentation. The challenge is in the authoring piece, and that’s why the WordPress interface was so nice when I started at Xero. When I left Xero, they had switched to Contentful as the headless CMS for informational pages while the API docs were being generated. I’m still waiting for a silver bullet, but maybe we engineers don’t like being limited and prefer to write their own destiny. It’s unlikely that we will embrace a single documentation solution because there are too many variables and ideas involved.

Phil Leggetter: I believe that we should focus on establishing fundamental standards for documentation, such as what types of documentation should be included and a standard journey through it. It would be great to see these standards adopted across developer platforms. Additionally, we should consider different types of personas and their mindsets when exploring documentation. Having defined types of documentation and journeys would be a better approach, and then tooling can align around enabling that. Ultimately, we need a set of really good documentation tools that enable these journeys and types of documentation. That would be a great future for documentation.

Interviewer (Sid Maestre): The developer journey and mapping multiple personas across touchpoints is something I’ve been thinking about. Regarding documentation, have we solved the problem of having good documentation? Can everyone have good documentation and do we need to aim for great documentation? What are your thoughts on this?

Phil Leggetter: I believe we should strive for great documentation, but what exactly constitutes “great” documentation is still up for debate. While there are some standard checklist points that good documentation should have, such as conceptual documentation, guides, use cases, API references, and fully documented SDKs, I’ve seen examples of documentation called great that haven’t stood the test of time. I think we need to first focus on getting good documentation before striving for great documentation, which will likely require an evolutionary leap rather than small steps. While tooling has helped us build good documentation faster, I don’t believe it has quite enabled us to achieve great documentation yet.

Interviewer (Sid Maestre): I think the advancements in API specifications and tooling have greatly improved the quality and accuracy of documentation over the past decade. In the past, documentation was often inconsistent and unappealing, leading to frustration and confusion for users. While we have made significant progress towards good documentation, we are still figuring out what great documentation looks like. I’m curious to know your thoughts on interactive API documentation, also known as API explorers, where users can make API calls and see the responses directly within the documentation. Postman also offers a feature where users can run API calls directly from the documentation using their API keys. Do you think this type of feature contributes to better documentation?

Phil Leggetter: In my opinion, having interactive API documentation, or API explorers, embedded in documentation is not fundamental for success. While there are certainly successful companies like Postman that use it, there are also many successful products that don’t have it. Personally, I prefer to get something running locally and experiment with it in my editor to achieve a specific piece of functionality. I’m not often in the mindset of just exploring without an end goal. Therefore, interactive documentation is not something I see as essential, but others may have more insight into its impact.

Interviewer (Sid Maestre): When I think about personas and their journey, having interactive documentation could be helpful for those at the initial stages of evaluation. It could save them the time of downloading an SDK or setting up a sample app. Additionally, less technical stakeholders may also benefit from experiencing it. I had a call with an APImatic customer who said that interactive documentation helped with the sales process. It could cater to non-developer personas who want to see how changing properties affects the payload or if the API solves their business needs. For hardcore developers, hands-on code may be preferred, but interactive documentation has its place.

Phil Leggetter: As you were talking, I realized that interactive API explorers could be useful for technical product managers exploring functionality possibilities. Companies like Rapid API or Postman call them workspaces. I remember Tim Bontel, the chief product officer I used to report to at Ably, often talked about the “art of the possible,” and I can see these types of product managers using interactive explorers to speed up their exploration process.

Interviewer (Sid Maestre): It’s interesting to think about where we are on this journey. If we map developer experience on the seven stages from infancy through preschool and adolescence to young adulthood, where do you think it would fall?

Phil Leggetter: I think our current state of developer experience falls in the young adult stage of the growth and maturity life cycle. We know what we’re doing, but there’s still a lot of room for improvement, especially in terms of standardizing tooling and enabling a great developer experience. However, the next iteration of developer experience needs to be a rebirth that incorporates AI technology and a change in the way developers interact with technology. We may see more interactive and Q&A-based documentation in the future, driven by changes in societal norms and expectations for technology interaction.

Interviewer (Sid Maestre): I find it interesting and agree that chatbots are becoming smarter with technology like ChatGPT. The potential for AI in the future is similar to how the iPhone became a necessary tool in daily life. In terms of developer experience, having information readily available at the moment would be a great goal to achieve. The current struggle with static documentation is serving all touchpoints within a developer’s journey, so AI could bring about a new era of interactive and personalized documentation.

Phil Leggetter: I’ve heard a lot about contextual documentation, but it’s difficult to achieve with current tooling because of privacy concerns. However, AI is being adopted with tools like co-pilot that help expand data structures and complete code. It would be great if the experience moved further into the IDE, with a panel that contextualizes what you’re doing and provides more information. This could be a slight evolution rather than a rebirth, but still cool. It would also be amazing to have prompts that customize answers for junior and senior developers based on their level of expertise.

Interviewer (Sid Maestre): Can you share with me what’s making you happy now? It could be anything from books, TV shows, games, or any other aspect of your life.

Phil Leggetter: I’m happiest spending time with my three boys and playing computer games. I’ve gotten back into gaming and enjoy playing colony sims like Stranded Alien Dawn, as well as city building games like Farthest Frontier, which is in early access on Steam.

Interviewer (Sid Maestre): It’s been great catching up with you.