Developer portals act as a conduit to collect data through your APIs to inform your future business strategy. As a dynamic work in progress, the strategy for a developer portal should be informed by objective data. A business organization is a complex adaptive system, and the developer portal is the intermediary to its environment.
You don’t need to be a Zero Gravity customer to start on the journey towards deliberate complexity managed through your developer portal. Read more to find out how Pronovix services help you to take steps to identify your developer portal needs to move forward within your current developer portal.
Our goal is to help you to outline the content and functionality of your developer portal. Through this, to increase your team’s overall productivity by lessening the time, expense, and iterations required to get to done.
In this article we discuss:
- How do you identify the needs of your devportal within your organization’s ecosystem?
- How do you build your developer portal with an eye for strategy and design?
- How do you collect data for strategic decision-making?
Introduction
There are many moving parts to the documentation hub used by developers and business decision-makers to discover and adopt your integration technologies. Behind the scenes, there are:
- multidisciplinary teams who need to work together to collaborate on strategy,
- a long term picture that prioritizes developer portal requirements, and
- a need to have a focused understanding of your developer or non-developer audiences to target user journeys within your developer portal.
In line with our motto, Grow and help grow, we aim to help customers with their portal’s overall developer experience, while indirectly supporting the success of their API programs. As a dedicated developer portal specialist, Pronovix is often in the unique position of observing and working with the challenges our customers face and exploring how their developer portals can be made more effective.
Pronovix can help you by
- providing an objective, critical evaluation of your developer portal as a 3rd party
- prioritizing functionality—contribute to your roadmap and strategy
- identifying obstacles to developer adoption/engagement
- empowering your team
Learn from our developer portal specialists
- how user experience (UX), user interfaces (UI), technical content writing, or other development services can benefit your developer portal
- what components of a developer portal are necessary for you
- how to improve the overall user experience or content of your developer portal
Table of Contents
- How to identify needs within your ecosystem
- Using services to outline long-term goals
- List of services for evaluating developer portals
How to identify needs within your ecosystem
While our goal is to turn our customer’s developer portals into adaptive products, the reality is that most of our customers need to start their devportal as a project. That is why we normally see three initial stages to a developer portal’s lifecycle with a pause before continuing into the fourth stage. How you progress between and within each stage is dependent on your objectives. Typically a customer journey involves getting a developer portal up and running quickly, identifying and iterating on the desired functionality, and finally maintaining the portal solution.
Four stages of a developer portal
- Creation of new devportals
- Alignment iteration through long or short-term development cycles
- Maintenance analysis of existing solutions
- Continued evolution expansion beyond catalogue functionality
In 2020 Pronovix introduced a Devportal maturity model to help discuss developer portals through their relative successes in the categories of developer experience, operation excellence, and business alignment.
Using a maturity model, we can ask:
- How do you increase adoption, usability, engagement, trust in my portal?
- What operational limitations need to be overcome?
- Is the portal aligned with its long-term business goals?
Developer Experience
Developer experience is user experience targeted to a technically savvy audience. It’s not just the quality of the technical documentation. Technology products are discovered by people through search engines, word of mouth, online forums, and exposure at events. When a person accesses a developer portal, they expect to be able to digest the content and information that is on display. A well-designed developer portal will have an information architecture that guides the site visitor through navigation, content, and a journey of discovery. Developer experience is apparent when you see:
- Navigation menus that make sense
- Search engine or ease of finding products
- Customer journey points (e.g. Learn, How to start, Discover)
- Accesibile design practices
- Trust signals and best practices for engagement
- Try out options
- Support & Help possibilities
Operational Excellence
Not all websites or developer portals are built the same way. How easy is it to maintain your developer portal? Are there people who push through significant friction to contribute to your portal? Do you wonder whether your developer portal is sufficient as a static site-generated documentation site or have your needs evolved to require a content management system with hierarchical content and navigation?
A ‘mature’ solution is what best fits the intended functionality of your developer portal.
Business Alignment
The portal’s alignment with the whole business organization’s goals is a sign of developer portal maturity. The devportal is constructed with a defined purpose and is actively driving business needs. For example, the use of Search Engine Optimization (SEO) is a marketing strategy that is overlooked when marketers are not involved in the content strategy for a developer portal.
We ask:
- Is there a business model for this portal?
- Are there clear business drivers for the products within this developer portal?
- Who are the primary stakeholders playing a part in the developer portal design and maintenance?
Using Services to Outline Long Term Goals
Our DX and UX services, through workshops and analysis, can identify what your developer portal needs. The results contribute to finding the software-related solution more efficiently and to increasing overall productivity by lessening the time, expense, and iterations required to get to done.
We start at project initiation by asking:
- Do you have an existing developer portal?
- What are the business goals?
- Who is this portal for?
- Who inspires and who competes?
- How do the features and functions fit together?
- What kind of content is needed?
- Focus on UX and DX: what will happen, why, and for whom?
- Do you have specific requirements which would require a more in-depth analysis of your target audience to understand what would serve you best?
- Could an evaluation of your existing portal help to understand current needs and future plans?
List of Services for Evaluating Developer Portals
These services aim to identify steps for the plan and design of your developer portal, information gathering for strategic decision-making, and other tools to help you to reach your next milestone.
Strategic Planning & Design of Developer Portals
These services are used for planning new developer portals or redesigning existing ones. All of these services can also be tailored around a specific use case of a developer portal, for example, onboarding experience or site navigation by a particular audience.
At Pronovix, we offer three UX packages. To help decide which one is needed, here are some prerequisite questions:
- Do you need an internal or an external developer portal?
- How complex are your requirements (e.g. technical needs)?
- How much content do you have?
- Do you need help outlining long-term goals and needs?
- How many teams are involved?
- In the case of many teams, is there mutual agreement or a need to align?
- Do you have predefined business objectives and user needs?
1. Short UX phase
API programs looking for a starting point to storing and making APIs available in a developer portal will benefit from a short UX phase. For example, a start-up or an enterprise company that would like to experience the most basic functionality of a developer portal. During the short UX phase, the focus is on the typical user personas and journeys for most developer portals.
If you prefer the long-term focus, skip to the Information Architecture Workshop.
Applicable for:
- Internal/External developer portal
- Simple technical needs
- Some basic content
- Short-term goals/plans
- One team of stakeholders already working together
- Predefined business objectives and user needs
A short UX phase is beneficial when you have basic needs, some available content, and/or only short-term plans. You need a place where APIs and documentation can be accessed. From a technical standpoint, you don’t need many, if any, customizations for your developer portal.
The basic Zero Gravity portal looks adequate and, if anything, may have more features than you feel you need at present. You see it as an investment to contribute to your growing API program. In this case, the established Zero Gravity Developer Portal structure is the main focus addressing the most typical developer portal personas, the developer and the business user.
2. Concept Validation workshop
The concept validation workshop focuses on business goals and the user perspective. It outlines and aligns user persona needs, behaviors, and key goals, configured within the Zero Gravity developer portal. The workshop validates your ideas and inputs/assumptions. The desired outcome is a structure for a development phase or milestone for your developer portal.
Applicable for:
- External developer portals
- Complex needs
- A large amount of planned content
- Long-term goals/plans
A concept validation workshop benefits companies with a great deal of subject area expertise and clearly defined business goals. You are aware of your users’ needs and know how the portal should look. You have content that can be implemented immediately and are interested in getting up and running as soon as possible.
This package is based on templates but adds the users’ perspectives. We still focus on the typical audiences while adding value by outlining user needs, behaviors, and key goals. The workshop works to align ideas and input: both Pronovix and the client pool knowledge to design for optimal developer portal experience.
3. Information Architecture workshop
You benefit from an Information Architecture workshop when there is complexity in your developer portal needs. For example, the need to consider content, users, additional feature requirements, and alignment of internal vision. The focus starts with your long-term goals for your developer portal strategy. We can help outline the map or milestones (phases) necessary to achieve your goals through a series of questions and answers. We work with you to look at your audiences, content, and customer journeys to create an easy to discover/digest structure for the developer portal.
To find out more, read Building developer portals step-by-step: Information Architecture Workshops at Pronovix.
4. Technical Writing workshop
Our Technical Writing services vary from full documentation support—taking the pen in our hands—to consultancy—where we collect and review your existing documentation and then share our suggestions with your team for your benefit. As an initial step, we set up a 1-hour call with your team to define the scope of the work and share more details.
Strategic Decision Making for Developer Portals
The following reviews, surveys, and studies contribute to data-driven strategic decision-making by providing you with the data that you need to make informed decisions around developer portal planning, API programs, and understanding your users better.
1. UX Services
Devportal Review
Inspect the devportal to identify and address the problems connected to the devportal strategy, API documentation, and developer experience.
Devportal User Survey (Usability Questionnaire)
A usability questionnaire focusing on developer portal usability, engagement, and trust signals. For statistically reliable data: feedback should be collected from at least 100 users. If this is difficult, an option is to combine the survey with another service.
Devportal Usability Test
The devportal usability test can uncover problems with usability, feedback on what works well, and opportunities to discover and learn about user preferences. One cycle of usability testing requires 3-5 users. Users receive targeted tasks and are observed. We ask: can users navigate well on the site? What are users struggling with? What confuses users?
2. SEO Analysis
Public developer portals usually receive high traffic from organic sources. Our SEO analysis sets up an action plan that aims to improve the discoverability of API products and strengthen trust signals towards the portal’s audience. As part of this analysis, a site SEO audit uncovers any technical issues from missing or improper title tags to indexability problems and much more. Search result analysis helps understand the proportion of the portal’s organic traffic and provides valuable information regarding long-term content strategy.
3. UI Services
The UI Design review is a UI review based on your brand guidelines. We use your basic brand rules to report on UI design-related errors, improvements, and quick-wins that can then be incorporated into the development strategy of your developer portal.
4. Technical Writing Services
Pronovix can help outline a content roadmap and provide guidance at each stage to help you to fulfill your devportal needs. Based on your needs, we can help provide you with examples of how to make the most of your devportal. We work with you to improve your existing content to make sure it is consumable by your audience. Most importantly, as a start for your Zero Gravity developer portal journey, we can help get your existing content migrated or implemented into your new site design. Our goal is to empower and support your team to create and maintain excellent developer portal content.
Standard Technical Writing Services
Included in the SOW (statement of work) is the latest Zero Gravity developer portal user guide and, by request, a demo for content management, workflow guides, and custom feature documentation.
Content Quality Review & Report
A content quality review is recommended for customers with existing content who will be migrated to a Zero Gravity developer portal or who are hoping to improve their content within their existing developer portal. We conduct a detailed review of all available materials, content, landing pages, and resources.
We provide an objective report that lists the strengths and weaknesses of your documentation and suggestions for best practices. We include action points with explanations to help illustrate pain points and evaluate the necessary effort to change. With the help of this report, your team can start improving the readability and overall quality of your documentation.
Content writing - Writing templates
We can provide writing templates to ensure that important information is shared with your users to provide an understandable and consistent structure. In addition to this, we provide content writing outlines such as for API summary page or landing page templates. For other types of documentation, we can prepare more templates on request.
Content writing - Full Content
If your team does not have technical writers or people responsible for marketing content, in collaboration with your teams, we can help determine what resources you need. Depending on the scope of the project we may provide some content writing service to initialize content for your pages. However, for the long term we prefer to work with your people to set up processes, templates, and guidelines, that they can use moving forward.
Extending your Developer Portal
Where the complexity of a developer portal dictates the need for additional features, we are cultivating an extension catalog that builds on the out-of-the-box experience of Zero Gravity developer portals. This means having a ready list of additional features that have been ideated or developed internally or for a variety of external (customer) use cases. Extensions include single sign on (SSO), multi-gateway integrations, Apigee monetization and teams, advanced role-based access control options, and more. Although these features are occasionally a one-click or configurable solution, more often than not, it is a feature that has been ideated on and requires development work to customize or to implement within your developer portal. Related terms with more articles in the works: codestewardship, feature catalog, extension catalog.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
