.jpg)
You’re in a dark place—your services have sprawled, you don’t know what’s in them, how up to date they are, which resources are attached, or who to even ask. If this sounds like you, you may have already enlisted an Internal Developer Portal (IDP) to help. IDPs make it easier for your team to find, build, and improve services and resources. But maybe you’re not quite there yet. Maybe you know you need to think more carefully about the foundations for that work—how you categorize and elevate information to the right people at the right time. If that sounds more like you it’s time to start mapping your information architecture (IA).
But first, what do I mean by “information architecture”? In short, it’s the practice of organizing content in a way that makes access to information quick and reliable. Historically, this phrase is most often used to describe website design—how to eliminate information bloat for the quickest path to conversion. But it shouldn’t take much imagination to see the parallels between this application, and engineering teams looking to provide “golden paths” for their developers via internal developer portals (IDPs). Both require a strong foundation of knowing what’s important to whom, and both have an end-goal of speeding time to action. In this blog I’ll share how the Cortex Customer Engineering team used extended principles of UX design to build a new framework for guiding customers through the process of setting up their data model ecosystem.
When to begin
I’m always surprised to hear how many engineering leaders believe they should defer their IDP journey until they’ve locked every aspect of their IA—every entity, every dependency, every rule, every exception. They believe structure begets speed. In fairness, I’m equally surprised by the other end of the spectrum—those that blow past this pre-work in their enthusiasm for building net new services and resources. They believe speed begets structure—as they replicate what works.
But much like web design, you can have both. You can begin to create an overarching structure while still moving quickly against near-term goals. Ask yourself what initiatives you have on the horizon that would benefit from this shift, and what smaller sections you can carve off to test ahead of a greater shift. While completing your IA might be a bigger exercise than you realize, it can also be an iterative process—one that allows you to extract value every step of the way. In the next paragraph I’ll use a needs-based model to help you clarify why, and when you need this work completed.
Documenting your “why”
Let’s start with a basic question: Why do you want to organize your data model ecosystem (DME)? Generally, you can separate the why into two buckets:
- Business Needs; and
- User Needs
The business needs are usually pretty simple; to save money, to make more money, or to be able to make better business decisions. Your “why” doesn’t have to be just one of these. In fact, it’s most likely a combination of all three. “We want to organize our DME because we know that whenever there’s an outage, we’re wasting a lot of time and resources, and we’re losing money, because we can’t figure out how our DME dependencies or who owns them.” Whatever these business needs are, be sure to record them early, as they’ll inform decisions you make about your architecture down the road.
How about user needs? Let’s consult those UX principles I mentioned earlier: Peter Morville and Louis Rosenfeld (Information Architecture for the World Wide Web, 3rd edition) posits that the IA of a website needs to address four main user needs:
- Known-item seeking: Users will come to the website to search for something desirable and known.
- Exploratory seeking: Users will come to the website looking for inspiration. They’re looking for something desirable but not sure what exactly.
- Exhaustive research: Users are in the process of extensive research. They want to find as much information as possible.
- Re-finding: A user needs a desired item again and is trying to find it.
While these were written for website design, Cortex has easily extended these principles to data model design. “Known-item Seeking,” for example, can refer to the process of Devs visiting an IDP to search for a specific microservice, its owner of a service, team that a service falls under, who’s on call for a specific group of services, etc.
There’s a good chance that your developers will face each of the above needs at one point or another, so it’s important to keep them in mind as you design your IA. And remember: Fulfilling user needs is often the quickest path to fulfilling business needs.
Five principles of information architecture for data model ecosystems
Once you've established your business and user needs to set priorities, there are several core principles that should shape your organization efforts. I'll be drawing from Dan Brown's principles of information architecture for website design to share how we think through building an IA for DMEs:
The Principle of Objects
“Content should be treated as a living, breathing thing. It has lifecycles, behaviors, and attributes.”
This principle comes from object-oriented programming. Essentially, each DME object type should be a template and should have “a consistent and recognizable internal structure” and “a discrete set of behaviors.” Let’s take a Team for example. A Team should probably be made up of: Members, services the team are responsible for, documentation relating to the team, etc. And it should be that way. Every. Time. As for behavior, you can assume that maybe teams will split into multiple Teams, or that Teams will cease to exist if priorities change. Following this principle will give you multiple different ways to “sort, expose, classify and connect content of this type together.”
The Principle of Choices
“Less is more. Keep the number of choices to a minimum.”
This one is pretty self-explanatory. Try to minimize the amount of choices given to a developer at any given time. For example: When a developer is doing some Exploratory Seeking (coming to the developer portal looking for inspiration. They’re looking for something desirable but not sure what exactly), you don’t want to bombard them immediately with S3, Lambda, Dynamo DB, EKS, EC2, App Engine, Big Query, etc. Maybe just start them off with something like “Resources”.
The Principle of Front Doors
“Assume that at least 50% of users will use a different entry point than the home page.”
To modify this we’ll say: Assume that at least 50% of users will use a different entry point than the {services} they’re seeking. Sometimes they’ll be given a Team as a starting point to find a specific microservice or vice versa. Not everyone will be given the exact piece in your DME that they’re looking for. You’ll want to make sure that your objects account for this.
The Principle of Multiple Classifications
“Offer users several different classification schemes to browse the site’s content.”
For this principle we can change “Offer users several different classification schemes to browse the site’s content” to “Offer developers several different classification schemes to find what they need, how they want.” This ties back into The Principle of Objects and is related to The Principle of Front Doors. For example: A developer should be able to use a “Team” type to find services or use a “Service” type to find an attached “Resource”.
The Principle of Growth
“Assume that the content on the website will grow. Make sure the website is scalable.”
Lastly, and arguably most importantly, assume that your DME will grow—a lot. Is the current design of your IA capable of scaling with that growth? Or put another way: How might growth break your current design? With this, it’s important to remember that while specificity is generally a good thing, you may want to consider keeping your IA a bit broader, so that you can quickly introduce new components as needed.
It’s not to late to start... but it's not too early either
Hopefully after reading this you either A) have a bit more clarity about what originally seemed like an insurmountable challenge; or B) realize that there’s a bit more involved in this process than you originally thought. Keeping your business needs and user needs in mind while utilizing the principles above can help guide you through an IA process that can be extremely complex and, at times, frustrating. Regardless of where you're at, it’s never too late nor too early to start putting these ideas and principles into action. If you’d like our help in thinking through your approach, schedule time to meet with us today.
