In this article we will investigate developer portal anti-patterns - common solutions to developer portal problems where the solution is ineffective and may result in undesired consequences. We will point out anti-patterns that can lead to a poorly conceptualized and executed developer portal. These are portals that –by their very architecture, appearance, or means of use– are set up to fail in the long run.
Anti-patterns differ from bad practices when (Source: Agile Alliance):
- It is a common practice that initially looks like an appropriate solution but ends up having bad consequences that outweigh any benefits.
- There’s another solution that is known, repeatable, and effective.
Regardless of the route taken to build a devportal: these anti-patterns occur as a direct result of tight deadlines, inadequate planning, or when the conceptualization of the devportal is oversimplified and underestimated.
Many advocates for developer portals will encounter executives, managers, developers, and at least one product owner who over simplifies their API program’s need for a developer portal with at least one of the statements below.
How to (over) Simplify a Developer Portal
- The devportal will only be used by developers.
- There is no need for long term maintenance and support.
- Build the solution. The other departments/people in the company will adopt it.
- Documentation is just text we push up. There is no need to involve the writers and writer teams.
- Write code. Push it up. That is the only process that is important.
- This isn’t part of our core business.
- If at first you don’t succeed, there’s a hack for that.
- Developers are technical people, OOTB is adequate.
- Developers don’t care about their experience.
- There’s an application that is great for that functionality, let’s just link or embed it.
- Providing a developer portal is a one-time fix type of solution.
These statements singly or altogether effect the outcome of your developer portal. Assumptions that a developer portal is only for developers often leads to forgetting that the overarching goal of a developer portal is to improve the communication of your API program. Creating a solution in a bubble without including the voices of all of the people who will hold a stake (other teams, other departments) results in a developer portal with limited functionality. Documentation is never ‘just text’ and giving marketing and technical writer teams the flexibility and autonomy to innovate and diversify in their messaging contributes to the sale of those API products both internally and externally.
Treating a devportal as if it is not part of your core business will limit
- its overall acceptance within your company,
- the resources allocated to keep it functional,
- the support it receives from higher management.
The Anti-Patterns of Developer Portals
API Freezer #
With an API Freezer you can not find the API and there is friction around all the APIs and utilizing them. Simply put - it’s too hard to find. Why bother?
Objective: Provide documentation for our APIs
Example Execution: Build a devportal where APIs and reference documentation are tied together with Swagger UI. Realize the need for a search function, build a search function.
Experience:
- A developer landing on this portal does not know where to start to understand your API offering.
- All of your business units drop all their APIs into the one list.
- Trying to search for a term like “user profile” results in more than ten items.
- A product lead is unsure if their new API is duplicating an established API.
Overall Response:
- Low adoption and trust for the developer portal
- Demoralized product leads and developers
- Stunted growth and innovation
- Silo work environments
An example of an API Freezer is when a flat structured API devportal has surpassed its ideal number of APIs. To give a visual: it is a live directory of all of the APIs that are available paired with inconsistent descriptions pulled from code. The initial focus of the portal was to list the APIs with a secondary focus to show developer documentation via Swagger UI. Little or no attention was given to the established documentation protocols and to identifying what additional documentation should or could be visible to the directory. As a result, the devportal does not help to sell or showcase specific APIs. A potential developer consumer needs to hear about the API on a common thread or forum and search the internal or external web to find it.
In this case, the assumption has been made that the developer audience is knowledgeable of the API database. The developer’s experience with the developer portal is frustrating. The documentation may exist but has been left out because of the lack input from technical writers or other stakeholders in decision making. As the API program grows, additional departments adopt the developer portal but documentation is limited and encapsulated - there is no mechanism to find or expose relationships between documents, differentiate types of APIs, or use dynamic keywords to categorize them. The developer portal has reached an endpoint where a fix would involve scrapping the old and moving to a new revised solution.
Frankensite #
The cost of a Frankensite is that your API products fail not because of their merits but because of how they are packaged and sold.
Objective: Provide documentation for our APIs. Include landing pages. Showcase case studies and examples. Integrate with our services.
Example Execution: Build a devportal with a reference directory of APIs and documentation tied together with Swagger UI. Search function by Google. Add menu navigation to your company’s technical blog hosted on Medium. Code is linked to the GitHub repository. Integrate with UserVoice chatbot and link out to the API support documentation repository you have been maintaining there. Tie in an open source forum. Disclaimer: None of these tools and solutions mentioned for example purposes are bad for your developer portal. Defining site architecture and understanding your user journeys will help create a more seamless experience while incorporating all of the above.
Experience:
- A consumer developer clicks on a link to find help or documentation for the API they are interested in and can not find their way back to the developer portal or API in question without resorting to their browser history.
- A product lead looks at the devportal that has been cobbled together and decides to go to a competitor’s API because they feel more trust for the more polished devportal.
- Chatbot is the most used feature although the answers can be found via documentation in the GitHub repository, forum, or FAQ.
Overall Response:
- Low adoption and trust for the developer portal and its APIs
- People consuming APIs are lost and frustrated when navigating on the portal.
- High need for support and walk-through
- Many sources of truth for documentation
- Unclear how or where APIs are supported
While devportals can be built as either a static site or as a content management system and integrate successfully with many external tools and services, a Frankensite is a developer portal that is cobbled together with disparate elements and tools. For example a static site generator with some landing pages in html, Swagger UI to show API references, and a support widget. The limited configurations of these tools result in a portal that does not provide a unified experience. The devportal is chaotic to navigate with a jumble of different types of navigation and content styles. A visitor to such a portal would need to be cognisant of where they are and hope to find their way back to where they may need to be, usually via the browser ‘back’ button.
These portals happen when:
- The feature list included every need of sales, marketing, and professional services
- User journeys of the people using your developer portal are overlooked
- All the tools that your company has approved are used
- Every free open source solution that is cool and available has been added
- An existing/dated devportal has been adapted/hacked to changing/modern needs
- The developer portal is growing organically and unchecked
Most devportals that result in a Frankensite are a result of not aligning user needs and expectations with business goals before building the devportal. Companies that create a devportal as a one-off tool with a fixed end point quickly find that they need to implement services and tools alongside this portal as their audience grows. The developer portal has been generated without a clear indication of process or governance for documenting the APIs outside of developers pushing code. There is a general assumption that developers, as the audience, do not require optimal user experience: they are smart, very technical, and not particular, so they will figure it out. All of these assumptions are paired with the need to “just get a solution out there”.
The questions to ask here are:
- How can I structure my information architecture to be consistent given these integrations and tools?
- How do I make my design consistent and implement it so that the people visiting and using this developer portal have a good experience?
- Does it make sense to have ticketing submissions embedded in my devportal or is it better to link and have a clear exit with management elsewhere?
API Ghost Town #
Finding themselves in a Ghost town the user is left wondering, is this business still operating? How can I trust these APIs? Is there anyone out there?
Objective: Provide documentation for our APIs and grow a community of users.
Example Execution: Build a devportal that supports APIs and reference documentation tied together with Swagger UI. Include a blog, a forum, FAQ, and some landing pages.
Experience:
- Recent Twitter activity but the last blog post was published in 2015.
- The FAQ makes API references to outdated procedures and suggests how an API can access data from Jawbone (which shut down in 2017).
- The forum’s most recent 3 new queries, with oldest dating 2 years ago, have not been answered.
- Looking up a comment thread on the API in question you see a dialogue opinionating on whether people of a specific gender or race should be involved in coding.
- Is this company functional? Where did everyone go?
Overall Response:
- Early adoption of the devportal and APIs
- Diminishing trust in the devportal and the APIs over time
- Need for support is not met
- Unclear how or where APIs are supported
- Second guess if APIs are up to date and if company is still supporting the API program
An API Ghost Town is thorough and beautifully designed at first glance. The company invested $1M or more for the build and design but did not account for the people necessary to maintain and support it. As a result, although the APIs are meticulously kept up to date, you find the last blog post was written long ago. The FAQ makes API references to outdated procedures and the forum is populated with tumbleweeds and trolls. Failure of this type of devportal has come about less from poor planning but from poor execution.
Rather than spending a large amount of money at the beginning of the devportal journey, spend less and focus on a MVP that meets your immediate needs but allows for an iterative product and operating budget to help grow your audience. The best developer portal is limited by the people who maintain and support it. Forums should have an active community and a community manager. Blogs should contain frequent and relevant content. A content manager should periodically curate the FAQ and any other associated support pages. IF necessary, pull back on what you offer to what can be maintained by your team in order to resurrect a signal of trust.
Ghost Towns come about from making the decision early on that the developer portal is not part of your core business and as such, not providing adequate and ongoing support and resources to contribute to its success. The repeated theme that developers are technical people not particular about their experience is echoed in Ghost Towns: visitors are faced with outdated materials and forced to go at it alone. A developer portal is not a tool that can just be delivered and expected to function in one dimension. Providing the communication feedback necessary to show signs of life is vital to building trust in your API products and success for innovation and future works.
Tyrannical Toolchain #
When faced with a Tyrannical Toolchain - the tool is so broken and hard to use - why bother?
Objective: We need to document our APIs!
Example Execution: Build exactly what you need - APIs and reference documentation tied together utilizing a customized product.
Experience:
- Jan is the go-to for pushing documentation up for changes. Jan has scheduled document changes to happen every 2nd Tuesday of the month between 1-3 PM. Anyone who is submitting documentation has to send it to Jan prior to those hours.
- The devportal is maintained by overworked Raj. Updating any content is dependent on his schedule and whims. He responds well to donuts.
- Lisa’s full time job is curating the content on the devoportal. She collects and revises documentation, images, and marketing promotions, and does a fantastic job keeping it all up-to-date on the site. Her final task is to add markdown to the files and make sure that they will be assigned to the correct endpoints. She hates her job and wishes she could go back to her original career as a techwriter.
- The summer intern Jeffrey set up the process for publishing documentation and started documenting this process – but did not finish before leaving to return to school. We now don’t know how to update these documents. It may be better to create a new process.
Overall Response:
- Friction and frustration to people in the API upstream development process
- At risk to become an API Ghost Town
- Low internal adoption by other departments and business units
- The devportal is broken and malfunctions behind the scenes
- Negative association or outright rejection of the devportal internally
- Demoralized colleagues
A devportal with a tyrannical toolchain has limited administration functionality. What this means is that you need to ask a developer to push code for every documentation change. People are mandated to work within restraints to how quickly they can contribute to change control and how quickly they can respond to a support query. If the person in the toolchain leaves, there is a void in knowledge and resources for the devportal to continue functioning. We often hear “we don’t have technical writers” or “the developers provide the documentation” and often see a lone PM managing a giant blob of HTML that is the core of the developer portal.
The goal that was “a devportal that lists our current APIs and their documentation” should have been “a devportal that lists our current APIs and their documentation that we can maintain or delegate to many as our company grows”.
Tyrannical toolchains come about as a result of underestimating the devportal audience from the standpoint of internal people who provide important content to the devportal. This is the most hacked type of site where the people populating the developer portal are just trying to make it work in any way they can to meet their deadlines. Taking a thousand steps back and looking at the needs of your API program is a good way to realize the difference between investing in the design and usability of a developer portal for all involved parties versus relying on a full time employee to be the maintainer of a functional developer portal. A developer portal should never stop being a work in progress. As old problems are solved, new challenges will arise.
Conclusion
Assumptions that a developer portal is only for developers will lead down these routes. These types of sites also occur when one department creates a solution for multiple without taking into consideration that people of varying technical backgrounds will have a role to play. Documentation is never ‘just text’ and giving marketing and technical writer teams the flexibility and autonomy to innovate and diversify in their messaging contributes to selling those API products both internally and externally. Treating a devportal like it is not part of your core business will limit resources and support for creating a fully operating and designed solution.
We highlighted many mistakes that a developer portal can have, but the flip-side is that when someone is doing something right it is cause to take note and to learn from their example.
- Best Practices: How to Engage Developers with a World-Class API Portal by Wendell Santos
- Interviews with the DevPortal Awards Winners 2019 by Katalin Fogas
- Developer Portals Best Practices: Components
Acknowledgements
This article is based on the concepts, interpretation and examples given by Pronovix’ CEO and Co-Founder Kristof Van Tomme in his various presentations, workshops, and at the Pronovix webinar “Does Your Devportal Need a CMS?”.
Many thanks to Zoltán Gyulai, Kathleen De Roo, Mónika Alföldi-Zörgő, Anna Antal for reviews, Gábor Nagy and Dóra Jankai for images, and Laura Vass for editorial review.
