By Paul Preiss, of Iasa Global
I keep watching people hand junior architects the wrong two documents. Services and Landscape.
Someone gets promoted out of engineering, does well, shows promise, and within a month somebody drops the application portfolio on them and asks them to rationalize it. Or hands them a service catalog and asks them to design the target. And the poor person sits there trying to look like they know, because that is what we do.
So let me be clear about something before anything else. You do not start with Services. You do not start with the Technical Landscape. These are advanced BTABoK concepts. They sit on top of capabilities, quality attributes, decisions, tradeoffs, stakeholders and a working understanding of how your organization actually makes money. If you have not done those, come back.
But read this anyway. Not to do it. To see where you are going.
Because there is a thing that happens to architects somewhere between year three and year eight, and nobody warns them about it. Your scope changes underneath you. And if you do not see it coming you will fight it.
The elevator
Here is the shape of it.
You start with an application. One system, one team, one set of users. You know every table. You know who to call when it breaks. Life is comprehensible.
Then somebody else needs a piece of what you built. So you expose it. Now you have a consumer. Then five consumers. Then the thing you built stops being an application and turns into a service, which BTABoK defines as “a logical representation of a repeatable business activity that has a specified outcome.” Self contained. A black box to whoever calls it.
And then it gets consumed by hundreds of applications. And the decisions you made in a sprint two years ago are now load bearing for a business unit you have never met.
That is the elevator. Your scope rolls up whether you asked it to or not. Application, then service, then service domain, then capability, then the landscape. BTABoK describes the landscape as “the living environment of technologies, applications, and platforms in which architects create value.” Underneath it sits the Technology Capability Model, which is the list of what the organization must be able to do, mapped to whatever delivers each one today.
And here is the part that catches people. The elevator goes down too. A distinguished architect arguing capability investment with a board in the morning has to go read the code (yes even in the grand old age of AI) in the afternoon. The scope you can ride, up and down, without losing the thread, IS the seniority. There is no other measure that means anything.
Why the contract is the whole game
Once hundreds of consumers depend on you, one thing keeps you alive.
BTABoK says “service contract is key.” Three parts.
The service specification says what the service does and how you call it. Not the design. The interaction. Register Customer takes customer details, returns a membership number. That level or it is useless.
The service level agreement covers performance, availability, security, capacity, support response. Both directions. And the same specification can go out at different levels. BTABoK’s own example is Silver at 24 hours and Gold at one hour, identical capabilities underneath.
The commercial agreement covers cost, term, penalties, and what your consumer is forbidden to do with the data you hand them.
Write it before you design anything behind it. BTABoK puts the order plainly: “Before considering the detail design or blueprint of a service the contract of the service can be defined.”
And now the reason, which nobody tells you until it is too late. Because the service is a black box, you can change everything inside it without touching a single consumer. Replace the database. Fire the vendor. Rewrite it. Two hundred teams never notice.
Get the contract wrong and the opposite happens. Every internal decision becomes a negotiation with two hundred teams. Forever.
That is the difference between a service you can live with and a service that eats the rest of your career.
Level 2 or 3. Always.
BTABoK says a capability model “is not a product list.”
API management is a capability. Apigee is a product that happens to deliver it this year. Identity management is a capability. Okta is a contract that renews in March. Keep those apart in your head and in your documents or your roadmap turns into a renewal calendar and you will not notice it happening.
Then map at the right depth. BTABoK asks you to trace every application to the capability it supports at level 2 or 3. Not at the domain level. Domain level mapping is faster and it hides duplication, which is exactly why people do it. BTABoK does not let it slide: “three reporting tools mapped to the same capability is not efficiency, it is waste.”
Three questions decide your work whether or not anyone says them out loud. Which capability does this strengthen. What is its current maturity. Does this investment align with the transformation agenda.
The Capability Card is the tool. Definition, scope, value, maturity on a 1 to 5, the supporting software and infrastructure and information, processes, services, platforms, APIs, owner, technical debt, cost, roadmap.
Watch the ownership box. BTABoK says missing ownership is one of the most common weaknesses these workshops expose. Ask who owns it. If nobody in the room can answer, stop the workshop. You just found the actual problem and it is not a technical one.
The estate you are joining
BTABoK is blunt about what neglect costs. “An unmanaged portfolio is the silent killer of technology value.” And “without stewardship, redundancy creeps in, costs rise, and fragile legacy systems remain critical far past their safe life.”
Four things.
Give every application a lifecycle state on day one. Innovate, Grow, Sustain, Decommission. BTABoK warns that applications without a state “drift into ‘forever sustain,’ creating hidden debt.” Record the next decision with a date. Keep, modernize, migrate, retire.
Fill in the record. Owner. Purpose. Primary capability at level 2 or 3. APIs exposed and consumed. Dependencies. Information domains and sensitivity. SLO, RTO, RPO. Costs. State. Health. Next decision and date. BTABoK says one or two hours per record is enough.
Record quality attributes as measurements. Security, resilience, usability, performance and sustainability all fight each other. Low latency costs money and energy. Tighter security costs usability. Use signals, not adjectives. Latency and error rates. Date of the last penetration test. RTO and RPO and the date failover was ACTUALLY tested rather than documented. BTABoK: “An application that is technically ‘sustained’ can still be a liability if it cannot meet basic resilience targets or creates ongoing usability pain for customers.”
And count before you split again. Every service you add is paid for in versions, deployments, installation, operations and monitoring. BTABoK: “If the cost for managing the services outweighs the benefits of flexibility it may be more advantageous to consolidate services and avoid fragmentation.”
This is crazy hard
I want to be honest with you about the size of this, because most of what you will read online is written to make it sound like a weekend.
Moving an organization to services is one of the hardest things our profession does.
You are asking teams to write a contract before they write code, when their entire incentive structure rewards shipping. You are asking them to keep services stateless, which is easy on a slide and brutal in a system that grew up around a session. You are asking for an owner on every capability, in an organization where ownership is how people get blamed. You are asking domains to expose services to each other, which creates dependencies that somebody now has to maintain across a boundary and across a budget. You are asking for TIME decisions, tolerate, invest, migrate, eliminate, on services that people have careers attached to.
And you are asking for all of it while the portfolio keeps running and the business keeps changing.
It takes between 5 and 8 years to build an architect who can do this properly. It takes longer to build the practice around them. Anybody selling you a faster path is selling you something.
Is it worth it? Yes. And I do not say that lightly.
Because a landscape where every service has a contract, an owner, a capability, a state and a cost is a landscape you can change. Change is the whole point. Everything else we do is bookkeeping.
Where you actually start
Not here.
Learn one application properly. All of it. Then learn what capability it serves and be able to say it in one sentence to somebody in finance. Then find the one service in your organization that hundreds of things depend on, and go read its contract. If it does not have one, you have just learned more about your organization than any document will teach you.
Then come back and read these two concepts again in three years, when the elevator has moved you and you can feel what they are actually describing.
The profession is worth building. It just takes longer than anyone wants it to.