This article talks about maps and navigation. Specifically about mapping code and services to gain team insight. It's my go-to tool when confronted with codebases and systems where we lack knowledge to navigate change confidently and safely.

Codebase Mapping is a great way to capture what's slowing down change. It can help spot when change is going to delve into complex or dangerous areas. More importantly having a birds-eye view helps teams to become more effective: informing decisions and improving codebases.

I'll tell you how I build them, and how you can too. But first let me tell you a truth about code.

This code sucks!

There's no such thing as perfect code. No matter how well intentioned the writers have been, complex systems gather complications.

Put another way: most useful codebases suck a little, especially when you first work with them.

It doesn't mean the whole darn thing is not fit for purpose. It's new, different, and someone else's. And no one has given you the guided tour. Though, yeah, sometimes, that code does suck.

Managing and navigating code is hard

When I work with teams who want to understand and navigate their code, I often build codebase maps with them.

We talk, exploring what we know. Share stories and surprises we have from navigating this world. We highlight the places in the code where bad things happen, though no one knows why, and the great places they've found. Together we build the missing guide the team needs.

Over time they've become Pirate maps. Calling out the places where treasure can be found and where dangers lurk!

Dragons, Treasure, and Pirates, oh my!

Stories tell that Ye Olde Cartographers placed mythical creatures on maps to represent real dangers. Often these were placed to advise caution or recommend avoidance, though sometimes they were placed in empty areas no one knew much about.

Pirate stories often contain similar maps. Dangerous beasts, quicksand, and tricksy routes to buried treasure.

I like to use these metaphors to get a communal view of where code gives us bad feelings or where things don’t work, even if the team doesn't know why.

The team can then know where they’ll run aground, or where they’ll need a good wind to get through a tough time.

Its a great way of getting a message across that's easily understood:

show us your map then, landlubber!

Here's a simple mock map, made from the components I'm currently using. Real maps are often bigger and usually have many more components and information. There's some more complex ones below.

From this simple example - I hope you can see the start of the rich information they can convey.

Shaping a code map

If you have read this far, you probably fancy building a map of your own. Let me tell you how I approach it.

A key to map-building is to gather people together to share what they know and to ask for what they need. You'll also need a white-boarding tool that will let you draw out and adjust the map.

Map building is collaborative

Building a map is a collaborative effort. Those who know most about the world can tell stories and the map is shaped by what they know. Those who want to know more and want to own more: ask questions and shape direction by what they need to know.

The conversation that happens when the group chats is as important as the map that gets produced. This builds collective understanding beyond what's on the map.

That does not mean that good facilitation and preparation is not useful. A guiding voice helping everyone be heard. Assistance in narrowing and broadening focus. Ensuring key questions are heard. All add up to a great mapping session.

Great facilitation is a topic way too broad for this post, but at minimum, consider asking someone to the meeting to help everyone attending get the most of out of it. Keeping conversations away from blame is also important - the conversations should focus on growing navigation skills for future change.

Maps are focused abstractions

It's better for a map to be focused on a few facets of its world than to try to convey everything. Great maps ignore or distort reality to be really useful - giving clarity to something important but complex.

I often focus on code units, bounded contexts, interacting services; depending on the scale that needs mapping out. I then add additional information about quality and experience.

When you are building a map, if there is a problem to be surfaced or solved, go with shapes that help the team with that. There's no fixed format to a map other than it being an informative abstraction.

Three steps to building a microservice map in 2021

At this point you can probably start building maps on your own - go for it. But, if you want to know how I build them, let me be your guide.

I Start with Context - outlining the Coastlines and Continents

I like to work outside in and build the context the services and code sits in. Often my framing boxes - my continents - summarises the business context.

I ask: What work does this team own? and explore the jobs that the services and code does for the business.

Then I ask What does the work? and add in smaller units - often the services themselves.

I ask: Why is it there? What's it for? What's it do to gain further context that could lead to adjustments in the map.

We should end up with a lot of small boxes (code: services, modules, libraries) in large boxes that give the broad business context. Ideally close collaborators should be close.

2. I then add Scale and Complexity

I ask the group: what's big and what's small? to allow me to shape the bigger lumps of code in the map.

Size often relates to complexity, but not always. So I ask: What's really complex? What's hard to change or ship? I want to find out why if I can briefly and see I can capture that.

I also ask: Where are there tests you trust? What code sets a good example?

3. Finally add Tacit Knowledge gained from the group chat

Finally I ask open questions: What's critical to know if you are going to make changes? I make sure that the key issues raised in conversation are represented in the map in some form.

Often my maps are full of virtual post-it notes. I take a little time to tidy up to produce something that should have meaning to the team in 3 months time. If I can do this with one or more of the team, even better.

Terra incognita to terra firma!

If you are looking to onboard new members, hand over a product, or remove silos in your teams and get to grips with your microservices, community mapping can surface information in a way that helps everyone navigate your codebases better.

Do you have different way of getting a birds eye view of your codebases and services?