DEV Community: Matthew Reinbold

How to Improve an API Ecosystem with Mapping

Matthew Reinbold — Wed, 17 Nov 2021 21:21:35 +0000

Before promoting a direction to API leaders, all parties involved must understand where they are and what destinations are possible. A map helps simplify an overwhelming number of technologies, techniques, and ideologies into something approachable and with a clear way forward.

Ultimately, maps provide the insights about an ecosystem’s strengths and weaknesses, fueling conversation. API Ecosystems are complex. But mapping where you are and where you need to go doesn't have to be.

More at the original post:
https://blog.postman.com/how-to-improve-api-ecosystem-with-mapping/

Four Behaviors of High Performing API Teams - And How to Measure Them

Matthew Reinbold — Thu, 04 Nov 2021 20:11:31 +0000

One API ecosystem challenge I've had over the years is quantifying what "good" looks like (I've published that journey on my website, with pieces including "Rethinking NPS for Quality" and "How Reporting Can Backfire" ). Despite most organizations' desire to be "data-driven", much of the quality storytelling we do remains anecdotal and story driven.

On the one hand, quantifying abstract concepts like "maturity", "quality", or "maintainability" is problematic. On the other hand, quantifiable metrics like "time-to-hello-world" and "uptime percentile" don't describe the health of an API ecosystem or whether improvement efforts are improving the speed and safety of overall API development.

I joined Postman in April, just as the company was preparing its latest survey. I saw it as an opportunity to build upon existing industry devops insights by testing whether they also apply to API program performance.

In the 180th Net #API Notes, I deep dive on the Postman 2021 State of the APIs Report; specifically, what are the four behaviors of high-performing API teams? And how do we measure them?

More in the newsletter:
https://tinyletter.com/NetAPINotes/letters/net-api-notes-for-2021-11-04-issue-180-state-of-the-api-report

Amazon's Inconsistency Invites Imitation

Matthew Reinbold — Thu, 07 Oct 2021 16:56:00 +0000

Last week, Cloudflare announced their R2 cloud storage service, promising "full AWS S3 API compatibility".

Unfortunately, consistency across AWS APIs (or even within them) is not a thing Amazon is known for. Deliberate cultural decisions on team autonomy and decision making speed make it this way.

From a challenger standpoint, copying the AWS API makes sense: it lowers the barriers for customers to switch. Practically, however, it means that problematic artifacts of Amazon's culture end up persisted across the development landscape.

I dig deeper into what this means for the industry in my Net API Notes, Issue #177.

How To Overcome Change Resistance

Matthew Reinbold — Thu, 23 Sep 2021 14:57:49 +0000

You've got an excellent idea for your organization. You've spent time carefully crafting your story and begin to share it. Then something begins to happen; perhaps there isn't anything as dramatic as a slammed door or "NO" screamed in all caps. But there's a hesitation, an avoidance, or an ongoing series of "whataboutism" that increasingly frustrates and drains energy. Congratulations, change agent! You've met resistance.

Workplace changes are sociotechnical, or having both a technical and a social aspect. The technical change part is the mechanics of how a task is performed. There might be technical detail and nuance to be debated. However, what is a far more significant source of resistance is the social aspect of the change. Social refers to how those affected by the change believe it will alter their organizational relationships.

Change, even wholesome, necessary, and positive, can provoke a sense of loss in individuals. Sometimes this sense of loss is legitimate, like when a company closes down its "innovation hub" or no longer recognizes "Quality Assurance (QA)" as distinct from the engineering job family. In other situations, the change is perceived as a loss of dominance, control, power, and/or a sense of familiarity.

People react to loss in different ways.

Resisting Change

In one case, they dig in and close down. Those resisting demand what is lost be returned. Without a recognized, new identity for the participants, our change narrative induces a counter-narrative: an energetic incitement to return to the way things were.

As this classic 1969 Harvard Business Review article by American sociologist Paul R. Lawrence states, resistance manifests as:

"persistent reduction in output, an increase in the number of “quits” and requests for transfer, chronic quarrels, sullen hostility, wildcat or slowdown strikes, and, of course, the expression of a lot of pseudological reasons why the change will not work. Even the more petty forms of this resistance can be troublesome."

This response is so typical that many executives assume resistance to anything is inevitable. Yet, changes must occur for businesses to thrive. This doubly for the all-important "little" changes that constantly take place: changes in work methods, in routine office procedures, in the location of a machine or a desk, in personnel assignments and job titles.

"You never want a perfectly fit, coherent, and therefore stable system (therein lies stasis and death)... for a system to evolve and thereby persist over time requires a certain (unspecified!) resilience more so than stability." – Alicia Juarrero

Opening Oneself (And Others) To Change

The other way people might respond is to open up. This opening requires a shared assumption that there is something new here and that we will find our way into that newness together. What does that mean, practically?

The easiest way to getting buy-in to a change is when those affected by it are co-creators. While this participation may sound simple in theory, in practice, it does entail careful handling. Participation is a feeling on the part of people, a belief that their needs are being heard and concerns addressed. Participation is not inviting people to comment or attend a meeting and checking the box 'done'. Employees must be treated as having treasured insight and opinions rather than a target to be pumped for carefully calculated questions.

That is why the identity piece of our storytelling is so critical. A future vision they can relate to, and the relationships it entails, will mitigate the sense of social loss.

An API Governance Example

As companies grow, the complexity introduced due to fragmented API design approaches and ad-hoc, laissez-faire governance drowns any benefit the API ecosystem had while new. In this state, integrations take longer, meetings go up, and estimates get more untrustworthy.

As a result, leadership may move to establish one of any number of groups: Centers of Excellence, Design Guilds, Architectural Review Board, or API Champions. The expectation is that these specialists are inserted between the "doers" and the production environment. Their job is to ensure that designs are "done right", mitigating the mishmash (and related overhead) that the organization increasingly toils under.

The problem with this approach, if done unilaterally, is that leadership has introduced not only a technical change - the specific THOU SHALL and THOU SHALL NOT that moves an architectural style from descriptive to prescriptive. They have also changed an API developer's relationship with the organization by inserting an oversite group in the pipeline. The usual work relationships, not just between developers and their peers, but developers and their environments, were changed.

As I discussed above, changing the social relationships nets more than just "who moved my cheese" or "why wasn't I consulted" whinging. The sense of loss breeds resentment, resentment creates low morale, and the quality and alignment initiative meets resistance.

That doesn't mean the idea to decrease fragmentation and improve design cohesion was a bad one! What it means, instead, is that a different approach is needed. Rather than a top-down directive that changes the entire organization's working relationships, the affected parts of the organization should be invited to co-create the change.

That includes listening first, talking second. It could be that not everyone agrees on what the problem is. If people are given a chance to come up with ideas, discuss the ideas of others, or otherwise be involved in the process, they’ll become invested in the change and understand it better. It is also easier to build a future inclusive identity in your narrative if those people were involved in defining that identity.

In Conclusion

Change has both a technical and a social aspect. The technical aspect of change is about making a measurable modification in the job's routines or practices. Change's social aspect refers to the way those affected by change think it will alter relationships.

If we can get better about addressing the social needs of people during change, we will better positioned for long term success. Again, from the 1969 article:

The significance of these research findings, from management’s point of view, is that executives and staff experts need not expertness in using the devices of participation but a real understanding, in depth and detail, of the specific social arrangements that will be sustained or threatened by the change or by the way in which it is introduced.

Technologies come and go. But people remain the same.

Four Essential Elements for Organizational Change

Matthew Reinbold — Fri, 10 Sep 2021 17:22:50 +0000

In my last post, I talked about the importance of creating a plausible promise for system change. To briefly recap, a plausible promise must be (1) inspiring enough to attract others to participate and (2) stand a believable shot of happening given all other constraints.

But what happens when a change agent needs more than the elevator pitch? How does one move from a plausible promise to a compelling change narrative? The answer is crafting a compelling story for systems change.

Why Stories?

Storytelling is for more than just screenwriters and teenagers past curfew. Stories are how we articulate the world, our place in it, and the ability to change. "We're all-in on the cloud" and "We're an agile shop" are both story excerpts companies retell to shorthand how their technical work should be done.

Stories, particularly those repeated within organizations:

Appeal to our emotions, moving us to act in a way that dry, dispassionate analysis fails to ("I empathize with your pain.")
Simplify the complexity of the unknown unknows into a logical, repeatable set of causal relationships ("I now have words for what was just a gut feeling.")
Make abstract phenomenon tangible and thus changeable ("I can get my arms around it.")

Change begins when one of the existing stories begins to fail. This faltering could be due to scaling challenges, a strategic pivot, or marketplace disruption. Whatever the reason, the old narratives no longer work or seem incomplete given increased business complexity. When this happens, it is time to tell new stories.

Parts of a Motivating Story

Ask five aspiring authors what makes a good story, and you'll get six answers, two podcast recommendations, and the odd existential crisis. When it comes to systems change, however, the components are well known. To inspire change, a story must have the following elements:

A Clear Articulation of the Current State
An Attractive Future
A New Identity For Participants
A Path Connecting It All Together

A Clear Articulation of the Current State

Context frames and gives meaning to the change that must take place.

A story of transition will highlight how the past way of doing things is unsustainable, how it has lead to the current crisis, which requires new ideas (your ideas!) to overcome.

An Attractive Future

During disruption, past data is a poor predictor of a future state. Faced with uncertainty, people often take what they know about the past, combine it with their assumptions and emotional state, and project it on to the future, largely unconsciously. Deconstructing a group's assumptions and projections about the future requires careful analysis. If we can identify which beliefs are steadfast and which are loosely held, we can navigate this potential minefield.

A story must emphasize that the future is not a fixed, predetermined point but something that can be changed. We can't predict the future, but we can try to invent one with more desirable outcomes. If instituting a change is worth doing, we have to have a coherent story about the new possibilities.

A New Identity For Participants

System change requires working in new configurations, often with new (to you) people. Stepping beyond the comfort zone of our friends and colleagues means engaging with strangers and opponents who may not have a shared understanding. A story should enable people to recognize their shared interdependence in the system, thus creating a shared identity. It must show how the sub-optimal future cannot be solved by individual stakeholders alone and how a new network with new relationships can.

Keep in mind, creating change may not require everyone. It does, however, need to connect the people that need connecting.

A Path Connecting It Together

Above all, a story must point people in the direction of needed change. Part of this includes articulation of what progress along the path looks and feels like.

A vital aspect of a story is how it links current actions to the desired future destination. Connecting these things increases the understanding of our responsibility and agency within a system.

The path storytelling should emphasize more positive than negative. Change spurred by intrinsic motivation is more sustainable, or those internalized stories rooted in people's strengths, aspirations, and ability to overcome.

A Remote Work Example

Let's take what we've learned above and apply it to an area many businesses are currently wrestling with: remote work. Let's assume that you've stumbled through the past eighteen months, but you're looking for more.

Articulate the current state:

Remote work has been around for some time. However, during the Covid-19 pandemic, millions of individuals were thrust into remote work situations not by choice but by necessity. Some companies were able to cope better than others. More than a year and with multiple variants continuing to spread, leaders are challenged to go from merely surviving to thriving. Talented individuals have come to expect remote options. Companies that insist on co-location at some unknown point in the future limit themselves to whatever expertise happens to be within a geographical area.

Craft the attractive future:

We need to move beyond thinking about remote work as a temporary band-aid. Moving office ritual and routine to a Zoom meeting is not enough ("virtual happy hours", for example). Instead, we need to truly digitize the work, not just work digitally. Learning to do this effectively taps our organization into the best, brightest, and most diverse talent wherever they are in the world. It also positions our org for a future where adaptation and iteration will be the norm.

Define a new identity:

Getting there will require new management techniques. Communication is always a vital skill. But we must learn how to go beyond lowest-common denominator transactional interactions encouraged by digital tools to relational ones. Our managers and leaders need to be able to check-in with our employees, building trust and psychological safety, not just checking-up on WIP. If our managers can demonstrate the more significant empathic requirements of remote management, our people will deliver greater value while enjoying increased flexibility.

A Path To Connect It All Together

We need to revise our operating procedures, training focus, and performance review characteristics to get to that future. There is precedent: Gitlab, a company with a $6 billion valuation, has no physical headquarters and employees in nearly 70 countries. Automattic, makers of WordPress and operators of Tumblr, employs almost 1700 remote employees. By learning from their examples to prioritize the appropriate digital investments, we will embrace the sort of change that is more perpetual, pervasive, and exponential.

That's just a generic example. If you were to do this for your organization, this remote story would need to be customized to speak to the unique needs, incentives, and fears that exist. Begin sharing a version of your account with those you trust to give you constructive criticism. Then iterate.

Conclusion

Stories are critical for creating systems change and can be told by anyone. If we better understand the elements that go into a story, our messages will find more traction faster. Moving beyond a plausible promise to a full-blown change narrative takes work. However, if your idea is a good one, the results are worth it.

Changing Organizations With Plausible Promises

Matthew Reinbold — Wed, 08 Sep 2021 18:42:15 +0000

It is inevitable that, at some point, a passionate practitioner wants things to be better. Whether that is improved API design quality, greater developer autonomy, or increased product focus, these change agents want to nudge their organizations in new directions.

Knowing where to start, however, can be overwhelming. Feeling, on a deep, fundamental level, that a course of action is right can seem insignificant compared to the size and entrenchment of a complex system.

Clay Shirky wrote about the term plausible promise in his book, Here Comes Everybody. He defined it as "a message framed in big enough terms to inspire interest, yet achievable enough to inspire confidence."

That sounds straightforward on the surface:

Aim too high, and people will dismiss you as a liar, hopelessly naïve, or someone looking to sell something. Examples include "End World Hunger Tomorrow!", "6-Pack Abs In 6 Days", or "Generate Beloved APIs From Your Database Schema". It is hard to rally people to your cause if it seems unobtainable.
Aim too low, and nobody will be inspired to take up the cause. There's either too much specific detail or too little perceived reward to make it attractive. Urging that "Every field name must be written as kabab-case" is not the bold rallying cry you might think it is.

The challenge is to find the Goldilocks middle message: not too pie in the sky, not too in the weeds, but just right.

John Cutler is a product evangelist and coach. In his guide on sustainable change agency, he defines several ways you'll know when your plausible promise is working:

People begin to invite you to meetings to learn more about it
Other parts of the organization begin to adopt it
You'll have volunteers helping to grow the idea in new ways
Someone will try to take credit for it (a good sign!)
People will reach out to thank you

You want change. Identify what about that change will achieve broad acceptance. Articulate how the process for change is not only possible but probable in the current organization. Gaining critical mass is still challenging. If you start with a plausible promise, however, you'll have taken an essential first step.

"Never believe that a few caring people can't change the world. For, indeed, that's all who ever have." - Margaret Mead

When Reviewing Others’ Work, Ask ‘How’ Instead of ‘Why’ Questions

Matthew Reinbold — Tue, 07 Sep 2021 21:55:44 +0000

In my API governance experience, I interviewed a lot of teams. The purpose of those chats was always to reach a better understanding of the problem. A better understanding leads to better design. Most of the time, these conversations were amicable, easy-going affairs. One contributing factor that kept these affairs from becoming confrontations was when I switched from asking "Why" to asking "How" questions.

When you ask someone "Why" they do or don't do something, you'll inevitably provoke a defensive response. For example, when trying to learn more about somebody's API practice, I could ask:

"Why don't you have 100% contract test coverage?"
"Why aren't your API descriptions captured in a single, discoverable place?"
"Why did you produce so many microservices?"
"Why is your domain terminology inconsistent?"
And the classic catch-all, "Why did you do it this way?"

Each of those may be a legitimate question. However, the nature of the question comes across as a request for justification. Worse, answers to a why question immediately entrenches the person in a list, of their own making, of confirmation bias. What was supposed to be a positive discourse has turned exhausting, as each side attempts to prove that their approach is superior.

Asking "how" is much more productive. Reframing our points from earlier changes the questions to:

"How do you detect breaking changes in production?"
"How do developers discover and learn how to use APIs in your area?"
"How do you manage the greater complexity with your number of microservices?"
"How do you describe this concept within your domain?"
"How did you work through the difficult decisions in this design?"

Both the 'how' and 'why' examples address, roughly, the same areas of concern. However, the 'how' questions are more likely to result in people talking in greater length, detail, and thoughtfulness. They assist us in going further in exploration.

Asking quality, open-ended questions creates a better rapport and a clearer idea of how to help. And the faster we get to help, the sooner our customers will find success.

The next time you feel the urge to ask "why", try reaching for "how" instead.