My team owns several services. One is our primary focus: an accounts service. We have a plentiful stream of feature work and tech debt to address there, and everyone (engineers, product, design, management) is aware of its going-ons and going-wheres.

Two other services though, have to do with exporting our data to a third-party CRM, namely Salesforce. While they are important—our customer support and operations teams rely on Salesforce to follow up on leads and generate invoices—they feel like "add-ons" to our team. The services were written years ago by no one currently in the team. No feature work motivates anyone to learn the flow deeply. Except when (a) something breaks or (b) a new feature for accounts necessitates an update in the Salesforce flow to maintain status quo. In both scenarios, only an engineer can practically investigate what work must be done. So that engineer temporarily becomes intimately familiar with the Salesforce flow. But afterward follows a period of "peace"—no one needs to touch these services—the engineer loses familiarity—the PM loses familiarity (if they gained some via discussions with engineers)—and we start all over again, possibly with a different engineer next time.

Sooner or later there comes a time when we engineers need a product decision, whether to resolve a Salesforce issue, or to know how to reflect a new accounts feature in Salesforce. But there's no one who understands the system besides us.

Why are things this way? Is this just a reality we have to accept in the given situation? Akin to a "code smell," is there an organizational problem here? How can we navigate to a better place? Assume that I'm willing to speak to tech leadership for whatever change must happen.

I want to add one last thing: about documentation. There have been several attempts to document this Salesforce flow, but it's as if no one knows how to capture the details in a practical way, and in a way that 6 months later an engineer can fully trust that it's up to date and dependable for investigations and decision-making. "Sometimes customer support converts the lead themselves because it's the only way to add a purchase order number before creating their first campaign." "Customer support has to edit the company name to be exact or else invoices won't be paid." "Until the client fills out their company name, we use a UUID as a stand-in because the field must be non-empty and unique in Salesforce." "The following fields carry over from the lead to contact details." "The business address must be..." "If an account was merged..." It's just... indigestible. A high- or even medium-level document would miss all the details, which is why engineers have to read code to be confident at any point what's going on. A low-level document ends up being too much information to process and impractical to use or trust that it is absolutely up-to-date and correct.

  • 1
    You call these microservices, but the way you're describing them indicates to me that they are not so "micro" - you have a whole team extensively working on one, and the other ones aren't easy to understand and get into. Perhaps these are better called just "services", and presented as such to your technical leadership / management? Perhaps you could argue that the other ones should be owned by a different team? Is there a team (not necessarily made purely out of developers) that's more closely associated with the Salesforce side of things? Jun 15, 2022 at 15:22
  • 1
    P.S. The other two microservices seem to be doing the work of translating between two different models of the domain (one being how your system conceptualizes the domain, the other being the representation in Salesforce). That is, you have two different bounded contexts (in the actual meaning of that term) - so maybe the technical leadership should make a context map of the current state of affairs in order to understand how the two are interconnected, what should be changed, and how to reorganize the teams. Jun 15, 2022 at 15:22

2 Answers 2


I remember asking someone about how their company had changed as they had grown it from small to big.

They said that when they were small they tried to automate everything so as not to have to employ extra staff. Devs would write lots of applications to automate day to day business.

When they got bigger they employed people to do the tasks manually and got the engineers to work on the actual product. This was just cheaper than maintaining the helper apps.

In your case consider adding a "export to csv" button on your main product and hiring an admin guy or sales assistant or something to manage importing it to salesforce.

A human will be more flexible to change and as its their day to day job they will learn the process, remember and understand it.

  • I have noticed a similar situation in my company, things went from "be smart and do things only once" to "do things by brute force over and over". However, once you have something automated (no matter for how long) it's hard to sell (to the company) the need of "someone" doing the same thing manually. Overall If it's an occasional work (as seems to be the OP's case). But, the idea is good. Give someone the responsibility to learn and comunícate. No company knowledge should be in the limbo. It's counterproductive for everyone.
    – Laiv
    Dec 31, 2022 at 12:16
  • 1
    I don't know, say you have automated process X but after a while X is now X + y, a small extra step which can be manually achieved by anyone. You add y to the backlog but its full of similar small things currently being done by random humans. "Why arent all these things automated god dammit!" shouts the boss while banging on his desk!, "we need to hire 5 more developers and a project manager" you say, looking at the tasks the boss realises than non of the things are that impactful "Ignore them and work on new features of the main product!"
    – Ewan
    Dec 31, 2022 at 13:27

If you’re talking about details, yes this is normal. The big reason we use abstraction is so that we can forget the little details.

If you’re talking about being able to see what it does at a high level then this is a real problem. When deep in a rabbit hole it’s easy to forget to do the landscaping.

If that’s what’s happening consider spending some time refactoring to extract some high level abstractions. That way you can communicate to readers at a high level without drowning them in details. Good abstractions hide details.

To do this effectively you really need peer reviews that are focused on this issue. Once you’ve been down the rabbit hole you have the curse of knowledge. So you need feedback from someone who hasn’t. They will let you know how well your high level code communicates while hiding details.

It's important to understand that when it finally works you're only halfway done. The other half is making what works understandable. For example here's a walk-through of the bowling kata. It could be argued they were done on page 21. Yet this thing goes on for 40 pages. They keep refactoring this working code to add good names, better abstractions, and better organize the code. Once you know what working looks like keep a grip on it while turning working code into understandable code.

Successfully focus on that and in 6 months when you’ve forgotten the rabbit hole it won’t take you hours to get the gist of what’s happening here. You’ll see it at a glance.

When faced with this problem many developers give up on code and turn to documentation. Why? Because it’s easier. It’s just not as effective. When it comes to staying in sync documentation is worse than comments. That’s why I’m willing to work hard to communicate with code.

It’s work. No two ways about it. But well abstracted code is the best solution to this problem. So be kind to your future self.

It also helps to keep your micro service small. A lot has been written about how to do that but one of the most useful rules is that a micro service should be small enough that one person can maintain it.

  • I've been waiting to have time to try what you're suggesting and it seems like next month I will. What you're saying sounds right. In the meanwhile though we did try 1 thing that did add clarity: We went back and revamped all of the logs (rewording, consistent formatting, moving verbose logs to debug, adding higher-level logs that tell more of the "user story"). Will return here after trying to refactoring. Dec 28, 2022 at 21:00
  • 2
    @AndrewCheong what I like about that is it shows you're focused on communicating clearly. One of the hardest things to do in computer science is writing something that you'll understand 6 months from now. Dec 28, 2022 at 21:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.