Creating a developer portal
Many of Gjensidige's competitors are creating so-called developer portals that allow partners and competition alike to see and use their APIs. Should we make one too? We went to find out.
Finding the arguments
Gjensidige has shifted its position towards taking lead and carving new paths, so why should we consider doing something just because our competitors are doing it?
Being clear and simple
Today, we have close to 500 APIs across all of Gjensidige, and their documentation is painful to write, painful to find, painful to use and painful to keep updated.
While Confluence is easy to use for the documentation itself, they are impossible to find (sometimes even if you wrote it yourself). Also, the instant there's a change to the technical solution, its documentation is useless.
Being attractive
Gjensidige both depends on and benefits from its partnerships. To help our partners connect to our APIs today, they receive a PDF document by email. Of course our partners have many other reasons to choose us beside our lack of docs, but an easier and more modern onboarding couldn't harm the relationship.
Furthermore, good documentation is valuable for new developers who are piecing together the big puzzle that is Gjensidige. By making the onboarding easy to find and use, we make a better first impression and raise our devs to document their work well.
Meanwhile, our competitors are making their API documentation available to partners and employees in one space.
Being bold
Historically, Gjensidige hasn't been the most open of companies, aside from a few passionate people whose mission has been to share as much as possible. This is our chance to share more of our outstanding work, showing our partners and peers that we make brilliant stuff in a brilliant way.
Finding the people
We in Team Builders have some experience in trying to gather documentation under one roof (you're actually part-taking in our main effort as you're reading this). From this we've learnt many things, but most of all that you can't create a tool for sharing and a sense of community if the ownership isn't spread across its users.
Therefore, we teamed up with Team Integration (who create and govern most of our APIs) and Team Platform (who optimise the developer experience and are ambassadors of sharing) for a workshop. Our mission was to gather pain points and opportunities from all three perspectives, so that we were able to agree on whether or not Gjensidige needs a developer portal.
Finding the purpose
We discussed our differences and similarities, wrote on sticky notes and even sketched out three different solutions. Having analysed the outcome of this, we found a hypothesis on which we agreed:
We need to gather Gjensidige's technical solutions and their documentation in one space that allows autonomous and sustainable sharing. This will help technologists in and around Gjensidige find what they need and use what they find in an intuitive and simple manner, dressed in our own brand. Its purpose is increased reusability and knowledge sharing for a speedier and easier way to any goal.
So we concluded that we all saw a need for a developer portal in Gjensidige, and we even had some ideas on what it should include. Now what?
Finding the opportunities
As we would when developing any customer-facing solution, we started with interviewing our users. How else would we know what to make?
Six developers from different areas of Gjensidige agreed to meet with us and answer our questions. Based on the hypothesis, sticky notes and sketches from our workshop we crafted an interview guide and a very simple prototype.
We asked them about their main pain points with documentation in Gjensidige, what they consider useful documentation, what it's like to be new and go through onboarding, how they make use of other teams' solutions and whether they share their own solutions with other teams.
The prototype was not used as in regular usability test, but rather a talking point. This was particularly useful, as it gave the developers something specific to approve or disapprove, and helped us better understand their needs through iterations.
Their invaluable feedback was eventually boiled down to a handful key findings, which were placed into an Opportunity Solution Tree with two main outcomes: Improved documentation and improved onboarding. By using the tree, it was clear whether or not a developer portal could contribute as a solution to the pain points we uncovered.
Opportunities for a developer portal
These were the most apparent pain points we identified:
- There is too much onboarding too soon
- You depend on close collaboration with others in the beginning
- You are familiar with different technical solutions in Gjensidige "just by knowing them" or by knowing someone who "just knows them"
- It's hard to reuse solutions made by other teams – you may not know they exist, and they are rarely documented
- Some are hesitant in contributing to other teams' documentation
- Documentation defeats its purpose when it's incorrect, difficult to use or outdated
- Sharing your solution with others leads to dependencies that hinder speed and freedom in its further development
Finding the way forward
As I'm writing this, we're looking into how we might take this out of Figma and into your browser. We've received support from the leadership in T&I and all three teams have prioritised this work for this quartile.
We will develop a proof of concept that simultaneously allows us to create value for our current solutions.
Want to contribute?
We're open about our process so that we may involve you from the get-go – the last thing we want to do is create something you won't use. Reach out and share your vision!
