Management asking every team for architectural diagrams for their code.
Posted by thedifferenceisnt@reddit | ExperiencedDevs | View on Reddit | 42 comments
This seems like it could be a pre-layoff or pre-outsourcing strategy. Or maybe they just want to improve our codebases?
Anyone have any experiences of something similar? This is a mid sized well known company. A couple of years passed since the last layoffs
natescode@reddit
They're required where I work. As dev lead, I basically get paid to just make UML diagrams in EA architect.
They're import. They're documentation and a visual way to show the intended architecture. This facilitates architectural discussions or when we need to refactor code.
edwinjm@reddit
Use this free AI tool. https://deepwiki.com
zayelion@reddit
Cost cutting due to server cost most likely. They want to fix that and if they can't then workers.
zirouk@reddit
Or they’re trying to demonstrate the technical value of the company for a potential sale
madprgmr@reddit
More likely a potential buyer doing due diligence.
zirouk@reddit
Yes, that’s… what I said.
Majestic_Rhubarb_@reddit
With my autistic head on … strictly you didn’t say that … what you did say might be being done because of a buyer doing due diligence before committing to buy.
So you are both right 😊
zirouk@reddit
Yes, want to get autistic? The buyer isn’t doing it. The managers are. The managers are trying to demonstrate the technical value for the company. The buyer isn’t doing any of it.
The managers not doing this to make an advert for the local paper. They’re doing this because there’s a buyer sniffing around. The buyer is implied, the managers are gathering the evidence, to demonstrate the value.
Majestic_Rhubarb_@reddit
I think we both agree a buyer is making it happen, regardless of who is doing the work. And it could be the buyers solicitors or chief engineers actually engaging with the board initially.
But anyway this is all a bit pedantic and i know i started it 😆
edgmnt_net@reddit
Basically a cheesy pickup line taking the form of diagrams. Probably quite meaningless on its own.
thx1138a@reddit
“Did you hurt yourself when you fell from Kubernetes?”
FalseRegister@reddit
Would you need the details of _every team_ for that, tho? The CTO and a few senior devs would suffice
zirouk@reddit
It’s like showing the customer a photo of what they might buy, instead of just giving them a verbal description. The seller gets disputable evidence the buyer was aware of what they’re purchasing and the buyer gets disputable evidence describing the thing they’re supposed to be buying.
Organic_Battle_597@reddit
If you are like my company, it is just some "engineering" team without a real purpose in life struggling to justify their existence and business value by pretending they have the authority to tell other teams how to write code. And staffed entirely by unqualified people who haven't wrote real production code in years, if ever.
Did that sound bitter? Whoops.
Fortunately for us everyone knows the game and we just give them the bare minimum that they ask for, ignore anything they suggest, and gently tell them to piss off if they get pushy. They lack any actual authority to do more than send plaintive emails.
aedile@reddit
There aren't a whole lot of reasons to get EVERY team. The two most likely scenarios I can see are:
1. They hired an overpriced consultant like PWC to do some kind of review and this is part of the discovery. Maybe an acquisition.
2. This is somehow related to a SOX-type compliance request, or some other legal compliance.
No knock on management, they have their purpose, but the vast majority of management at or above the Director level couldn't read an architectural diagram to save their life, and really wouldn't know what to do with one if they had it. My guess is that either some external engineer needs to read it for some reason due to an engagement with the company or they are documenting as part of CYA efforts for compliance.
Moradeth@reddit
Had to do this when a security team was spinning up, they wanted to work on understanding the whole stack, and create threat models for every team as baseline.
elperroborrachotoo@reddit
Out of the blue, without discussing that with any team?
I cannot fathom any motivation to your advantage.
Check with the other teams if they had a day in it; maybe they were addressing quality issues this came up as a solution for improvement and someone mentioned this would be good for other teams, too.
But that feels very generous.
Ask for clarification. What depth, who's the recipient. Dazzle them with jargon, C4 or UML class or sequence or... Maybe they reveal some motivation.
(One could also just ask "why", if you are on good terms at least with one of them)
prshaw2u@reddit
Last couple positions I had an architectural diagram/documentation was required BEFORE starting any new project. So this could just be bringing the legacy code to a level to start this type of requirement.
And let me say that it does improve the code/design quality in a positive way, even if I totally hated having to create the documents required.
netderper@reddit
You should ask about the intended audience for the diagrams. Other developers? managers? marketing material? investors? Diagrams at the wrong level are about as useful as a box of rocks.
nickisfractured@reddit
Could be because a lot of teams are building subpar solutions that don’t scale and may have design flaws that can be caught ahead of the build. Most likely because issues have been getting worse and costing more money after the fact and they want to be as proactive as possible.
endless_shrimp@reddit
100%
You should have these anyway
Crafty_Independence@reddit
Or it could be they're dealing with millions of lines of legacy code that doesn't translate into a clear diagram. In which case documentation only takes you so far.
compubomb@reddit
Lot of products, lot of teams build s*** and they don't have any of this. And my last company I started generating that kind of content and they were like why did you build that? It's kind of worthless. It's going to go out of date. And I was like there's a reason why it's a markdown style mermaid document. Not everyone who writes code honestly even understands the utility in producing a lot of the documentation needed for long-term higher level understanding of a product life cycle. Especially people who supposedly manage the team.
BanaTibor@reddit
Make one for them. A very high level one. I worked on a parser-processor lib and managers kept asking question on the stuff all the time. I made a very high level architecture diagram with a few comments, it was simple, easy to understand and told them what they needed to know. It was like the holy grail for them.
PaulPhxAz@reddit
If you don't have this your team is probably mediocre anyway. I've fought a lot of battles over getting teams to 1) Make diagrams of the things they are responsible for and 2) Treat this as stewardship of their projects instead of "extra" work
ZukowskiHardware@reddit
Good, you should always be modeling before building anything. Then get it reviewed, then build something. It is much easier to move a sticky note than to refactor.
thedifferenceisnt@reddit (OP)
This is modelling "legacy" code. not what you describe
Devel93@reddit
It could also be compliance, what domain are you in, I had this when I worked for a medical device company. It's also used during acquisition
OTee_D@reddit
What do you mean with architectural diagrams for code?
If we talk class diagrams and control flow etc that can be generated by a lot of tools.
It's nice to have as a documentation ,but then someone needs to update everything when something changes. So many companies only generate those on the fly when actually needed.
Having your real architecture documented (main components, tiers, domains) makes sense. Otherwise quality deteriorates over time as every team member will build a little off, a little different and ot becomes a mess. Also this helps the devs to navigate where to put changes, extensions etc. At least the should develop according to your architecture, shouldn't they?
dnult@reddit
This isn't uncommon. One thing the diagram will provide is a better understanding of how systems are integrated. That is useful for disaster recovery, planned maintenance, or updates to the system.
SolarNachoes@reddit
We have these in spades on our wiki.
Can also generate them with AI.
Sporkmancer@reddit
There are two reasons I'd typically expect architectural diagrams to suddenly be necessary. Either additional investment into the company (through actual investors, selling, or whatever) is being sought and documentation supporting a supposed valuation is what's being asked for, or a (probably new) higher manager has decided that not having these is problematic. Neither of these likely leads to outsourcing, but it is possible that they're trying to prevent negative effects from a future layoff. Your knowledge and experience with your company may change the likelihood of any specific scenario, but that's my expected order of what's likely happening - much more likely valuation prep than any sort of workforce reduction or restructuring.
Keep in mind that if it is prep for selling the company though, that can be just as bad - maybe treat it as a yellow flag and start lining up another position just in case.
08148694@reddit
Not having architecture diagrams is reason enough to ask you for architecture diagrams
You should have them before you have the code
I wouldn’t look too much into it, if you’re worried about layoffs of outsourcing speak to your manager, don’t try to read tea leaves
yxhuvud@reddit
Is the management new? Perhaps they just want to understand the general shape of what you do?
rayfrankenstein@reddit
Management mandated actions without explanation or context are usually the harbingers of bad sh*t.
gemengelage@reddit
Might really be nothing.
I had a similar situation where they encountered some issues because a software was effectively orphaned, they tried to rehome it to a new dev team and realized that there was basically no documentation and the few diagrams and confluence articles they had were hopelessly outdated.
That problem got escalated all the way up and management reacted by forcing all teams to update their documentation.
You know, the usual management knee jerk reaction.
figbarjunkie@reddit
I'm in the same boat. The same thing is happening at my company and all those diagrams are getting reviewed in a call by the Senior Architect with other leaders of the org. We are specifically asked for the C4 diagrams, lol.
The thing that's happening with our company is that, almost all the roles of our org are being moved to India and people are expecting a layoff, coming January.
InterestRelative@reddit
It might be also pre-acquisition.
If it's pre-outsource, I doubt it will help outsourcers.
shelledroot@reddit
Really depends on how big/complex a team's scope is whether this makes any sense. Could be pre-layoffs, some shiny new exec trying to shake up the company, or a multitude of other reasons. Asking what insights they are looking to obtain may help clarify, as it stands this is too little information to act upon.
03263@reddit
Yes and it sucked because our architecture was cobbled together, not master planned. Reversing from that into a formal diagram is not easy, ended up faking it to look cleaner than it really is, basically the most common/happy paths and not documenting every edge case or hard-coded exception.
guardian87@reddit
When you say management, you mean engineering management?
That is very uncommon from my perspective. The effort in providing architectural diagrams can be quite significant.
In my organization we have a small architectural team and many domain teams. The architectural team provides "a reasonable level" of architectural drawings and component dependencies.
In our organization, some decisions are made top-down by management and the architecture team.
The teams in those boundaries can make their own choices.
If a team needs to do something that goes against our architectural principles, we discuss why and how to accommodate it (or we ask the team to take a different route).
This sounds like a stupid idea, but if it is necessarily related to potential layoffs or outsourcing is hard to say.
CanIhazCooKIenOw@reddit
What did your manager say when they come to you with this request?
Or what did your skip say?
You need to understand the request to better provide detail.