I think there's something else that's necessary that doesn't align well with the things in the article, and which is currently lacking in my current work environment, but which is kind of hard to describe succinctly.
Basically, my job requires using a lot of tools and technology and processes created by other people, but none of those tools are easy to use or well documented. In order to get stuff done you have to have a social network of people who know how to do the things you need to do, and know all the secret tricks. The right environment variables to set. The right arguments to pass to simulators. How to find the important bit of data buried webapp developed by people who apparently like to invent new words for old concepts. I get a lot of terse autogenerated emails that probably mean something to somebody, but not to me, and don't have human return addresses or really any way to discern the context of where they came from or why. A lot of tools use domain-specific configuration languages that are usually just python scripts that call a bunch of functions that are defined elsewhere and have no documentation.
These things might be reasonable in a startup with a dozen people, but we have over a hundred thousand. My opinion is that once an organization is a certain size, everything really needs to be written down and easily accessible. I shouldn't have to regularly ask people how to do basic things, it should be on a wiki. If it's complicated, it should be in a training video, or a user manual.
> These things might be reasonable in a startup with a dozen people, but we have over a hundred thousand. My opinion is that once an organization is a certain size, everything really needs to be written down and easily accessible. I shouldn't have to regularly ask people how to do basic things, it should be on a wiki. If it's complicated, it should be in a training video, or a user manual.
> Individuals and interactions over processes and tools
> Working software over comprehensive documentation
I remember when my employer adopted agile. One of the first things they did was lay off their team of technical writers.
Also you wasting your time flailing about probably makes some manager's budget numbers look good, because they got to "save" the money that would have prevented you from flailing about.
Indeed. It is too easy to read this as a rejection of tools, processes, documentation, and plans. That interpretation makes it harder for at-the-coalface employees to get help from leaders when they...
- actually need tools and processes designed to set the conditions for healthy interactions among individuals.
- actually need to spend time improving the documentation to enable them to produce working software.
- actually need to have a meeting-of-the-minds so they can collaborate with customers.
- actually need to spend some time planning so they can respond effectively to change.
Part of the problem here is that good technical leadership is waaaaaay more difficult than can be reflected in a 4-point manifesto. Whole books[1] are written about it. Part of the problem is information flow. It takes courage to speak clearly enough to tell leadership that they're so focused on being agile that it is harming social trust in their organization and preventing their teams from acting with agility.
[1] recommendations: The Toyota Way, Leadership is Language, Ego is the Enemy.
Maybe I have been lucky to never have experience a process heavy work place, but those two parts of the manifesto never made much sense to me.
Going Agile basically meant a return to caveman times. The only way to know anything about the code base is for the tribe's Elders to sit around the fire and tell stories.
Code doing weird thing X? Is it a bug? Is it intended? No way to tell unless I interview everyone who has ever touched the code base, and they happen to remember why they did that.
I get that the manifesto says favor "this" over "that" but don't discard "that", but everywhere I have ever seen it implemented they discarded "that".
Im going to have to disagree based on personal experience at my huge ass fortune 50 megacoprp. They JUST started adopting agile...JUST, I kid you not many teams are still officialy waterfall, even officially agile teams are effectively waterfall. It's going to take another 5 years for anything to stop looking like waterfall. And let me tell you, as much as people hate agile, the old way is not working, it may even take the company down. Anyway having had no agile...OPs Post rings very very true in my ears. There is an obscene amount of tribal knowledge that needs to get aquired. Sometimes if you're lucky and in the right chat, there's a one-note that gets passed around. We just started getting wikis.. and now they're transitioning to a different vendor. So some high profile teams working on safety critical teams have docs on both...but they aren't the same and both are woefully out of date, also you need manger approval to get access to either of them.
Yeah, Agile is not the OP's problem. Some director made some comments about a direction, and zoom! Off all the middle managers went, trying to kiss up to him, and implement what he said in the most dramatic way, in order to get that next promotion, or at least more headcount. And now it's, "Just the way we do things around here. Like it or leave."
His problem, as with all these types of things, is management. Of all people, we here on this forum ought to be able to call a spade a spade. But even we fall victim to blaming the process or the tool. Over and over again, the problem is management, and we should call it out.
The biggest problem with large corporations is managers who sacrifice long-term company success for short-term personal success. Smaller corporations can often get rid of such managers, but past a certain size -- and that's not really very large -- bad managers can become entrenched as they hire and/or promote sycophants to prop up their power plays. I have 27 years in the blue-chip Fortune 250 world, and I've seen it over and over and over again.
We're going to have to change large parts of the tax code in order to fix this problem, so that companies do NOT get a tax break by giving stock options as compensation. Until that is no longer the case, you will have people -- and rightfully so -- deliberately and predictably responding to huge financial incentives to do LONG TERM damage to the company with SHORT TERM thinking. The C-levels should stop this nonsense, despite the tax incentives, but, of course, the problem is only worse at that level.
Agile might not be my problem, but even so what the comment you're replying to kind of sums up the situation:
> I remember when my employer adopted agile. One of the first things they did was lay off their team of technical writers.
We had a big round of layoffs a few years back. I don't know if technical writers were affected more than others, but we did have a team whose main job was to run training sessions; how to write better code, how to be a more effective technical organization, that sort of thing. That whole team was laid off.
Management may be the problem. It's hard to point the finger at any one person in particular when everyone is just trying to do what they need to do to ship product, and the underlying problem seems to be a sort of emergent behavior that you end up with if you get a bunch of generally smart, helpful, friendly people together and apply all the wrong incentives.
Stock incentives might be part of the problem, but I expect that's more of an issue for the upper layers of management. Lower-level manager can't individually do much to affect the stock value one way or the other. I think maybe a mandatory long vesting term could help. Like, if you're a CEO your stock doesn't vest for ten years. (Maybe "vest" is the wrong word, since that implies you lose it all if you move jobs before it vests. I'm thinking of a system where if you leave you still get the stock eventually.)
You're taking those statements out of context read just a tiny bit further and it says:
"That is, while there is value in the items on the right, we value the items on the left more"
So it's doesn't say forget all processes and tools. Also I would say that most of these automated things the OP is talking about are processes and tools.
Hang on, don't blame the agile manifesto here. Blame the management that adopted the agile manifesto as "do all the exact same things we used to do that didn't work, but call it 'agile'".
I totally can, and will. It's on them if they popularized slogans that can be too-easily misunderstood. That's meant that agile, in several respects, has been an exercise of throwing the baby out with the bathwater.
> Blame the management that adopted the agile manifesto as "do all the exact same things we used to do that didn't work, but call it 'agile'".
We’re now at a point where the widespread and rampant destruction that’s been wrought in the name of agile is so bad that it’s not reasonable to say “oh you’re not doing it properly”.
That excuse could be used to avoid responsibility for literally anything.
Hype bros use that to defend token scams (“you just don’t get it”).
There’s an increasing mountain of evidence that shows agile just doesn’t work, makes things actively worse by forcing the creation and then concealment by neglect of engineering problems, and (as discussed above) actively reduces documentation so that agile cheerleaders can pin their incompetence on the engineers that inherit their mess when they cruise on up the ladder oblivious of their failures.
All of this and not a shred of empirical evidence, ever, that it actually achieves anything other than obscuring management stupidity.
> There’s an increasing mountain of evidence that shows agile just doesn’t work
Do you have any keywords I can search for to find this evidence?
I haven’t looked at in in ~4 years, but the Project Management Institute (PMI) used to publish some reports based on surveys that said ~70% of corporate projects fail. I am interested in comparing the evidence you’ve seen with the evidence the PMI has put together.
Edit: I think the language is “70% of projects fail to realize the planned benefits”
I haven’t looked at it in years, so I could be way off. I believe that projects that are completed 2 weeks late are classified as failures the same way a project that is abandoned half way through is.
Good ol’ intent vs impact. If you’re proselytizing something, it shouldn’t be judged by your intentions or how true it is, but the impact it has on the world. Agile was not great in that regard.
If I hear that damn mantra again, I'm going to puke. Xtreme Programming had it right
If you aren't writing the damn manual, you aren't delivering an entire dimension of product to your user.
I sat down a little while ago to an old 80's handheld digital business organizer. The device itself was meh.
The manual tho! My God, I'd forgotten what it was like to read a primer on a product that had actually had some effort put into it. People think UX replaces training/SOP's/manuals, and it really doesn't. Your manual is how you mass produce user expertise. Your manual, at least by consumer's opinion is the difference between Yet Another Agile Heap Of Kludged API's and Business Processes and a truly coherent whole.
The problem with most Agile extremists though, is they never take Minimum viable documentation to heart. Or they completely externalize the cost of clear, complete communication to the User. If I had to put my finger on why, it would be because Engineering spends too much time writing and not enough time using their code outside of bench testing.
This isolates from the consequences of poor decisions; and prevents people from facing the One Great Problem of Humanity: Communication.
Keep a bucket handy, because you are going to hear it again, because it often isn't. The fact that a million people are acting entirely contrary to the spirit and text of the agile manifesto, but calling it agile, does not change that.
>> If I hear that damn mantra again ... never take Minimum viable documentation
> But... you're not doing it right. Like, not at all.
Nope, sorry. You can't honestly say someone's doing it wrong, especially when "it" is defined so vaguely, or when "doing it wrong" seems to emerge from the document at least as much as "doing it right," if not more so.
> Where on earth do you get "don't provide user manuals" from the agile manifesto?
Where do you get "provide user manuals" from the agile manifesto"? The problem is that it's most easily read as a rejection of documentation, in general.
> Working software over comprehensive documentation
and use it as a reason not to do documentation at all. It's ambiguous, and can clearly be read as "you should not work on documentation when there is software to work on", and there's always software to work on.
It's perfectly OK to blame the agile manifesto. Part of the issue with the agile manifesto is it was written by developers, which makes it sound credible. In addition, you have a lot of cult adoption by developers, which made it difficult to refute. Once law is written in stone and some boundaries are established, that's when business processes come in and do what they do best: see how to manipulate their actions around that language to get what they desire from what is accepted/legal. They tend to always find paths around the bounds that lead to new undesired behaviors.
I used to run public community driven online video game servers in a different era and they were quite popular, sometimes the most active/hearts in their communities. One thing I always struggled with was writing down rules for player behavior on the servers. Once I write a rule it does two things: establishes what NOT to do explicitly, but opens a huge gray area of what isn't explicitly defined that can be done or opens up a subjective gray area that shouldn't be done but is not clearly defined. I now have to enumerate everything I don't want people to do which may be a massive list if you want clarity and no ambiguity. People get creative, always, and find new undesirable behaviors within your rule framework.
In the end, when you write some base rules, the only real solution is to continually ammend the bounds of your rule system over time to adapt and adapt, leaving less surface area to attack. This is why the US legal system is so darn complex. Basic constitional laws are established, some explicit don'ts, some explicit dos, and everything missing becomes questionable. I didn't want to do this on a video game server because... it's a video game server, nor did I have the time. I instead took the "it's private property and I am the tyrrant approach" and wrote a very simple rule to play with etiquette, then ruled over the server benevolently (at least I think so, joining anonymously for occasional sampling to adjust some server settings I found being abused and never banning people just because they were unenjoyable to play with) and it worked well. The servers remained the most popular servers.
The agile manifesto never adapted and business leadership is who calls the shots. A culture said let's adopt this and businesses said ok, sure, then this is how we're going to interpret these poorly defined bounds. You said this is what you wanted and everyone agrees so here you go. For the US constitution, vagueness and broadness works well because it was designed to be a living, extendable, changeable document. The agile manifesto is not. Given how well businesses skirt around the meaning of law to do legally, ethically, and morally questionable practices, what hope does some silly manifesto with no teeth someone writes have? Business rule as small little hierarchical dictatorships with tyrants ontop within a democracy and I've found the characteristics that compose leadership is often the opposite of benevolence. Be careful what you ask for in such environments, your requests will be twisted against you.
> Individuals and interactions over processes and tools
The points should be phrased "Processes and tools after individuals and interactions", meaning we want both, but one side first. In this case, it better implies we want processes and tools that work well for the individuals and their interactions.
Individuals and interactions over processes and tools
and we have mandatory processes and tools to control how those
individuals (we prefer the term ‘resources’) interact
> Poorly written or out of date documentation is worse than no documentation.
No, it's not. I _can_ be, but it can also be much better. Documentation is hard, we know that. But it's also incredibly useful in many cases. There are plenty of times where software is nearly useless, or the time required to use it becomes untenable, without documentation.
Honestly, I feel the same way about the code; if you can't be bothered to put a note in a file indicating what it's for (unless it's clearly obvious to a casual observer with limited domain knowledge), then you shouldn't be writing software at all.
If the software cannot be used for its intended purpose without some special knowledge, and that knowledge is not available to everyone who uses that software, then the people who don't have access to that knowledge are going to be unable to use the software for its intended purpose.
To some people in some kinds of organizations, this is a feature. The people with the hidden knowledge are more powerful than those without it.
If the software is written well enough that it doesn't need much or any documentation, then great! If that's not true, though, there had better be documentation if you want people to use it.
> Basically, my job requires using a lot of tools and technology and processes created by other people, but none of those tools are easy to use or well documented.
When I first moved into management roles I didn’t fully understand how much of my job would be simply saying “no” to a constant stream of engineers wanting to write or rewrite custom tools, libraries, frameworks and platforms when otherwise sufficiently good alternatives already existed. Not all engineers, but once you get into a big enough organization there are a lot of engineers who want to do meta-work and rework things instead of actually shipping things.
The worst offender I worked for had meta-tools on top of everything. You couldn’t use GitHub, Slack, or even our cloud platform without first learning how to navigate all of the custom tools and bots that had been put together to gate access to everything and make it work. And like you said, it was poorly documented. It turned into little fiefdoms where you had to know who to talk to if you wanted to get past the systems to get things done.
This can all be avoided with good management at an organizational level, but of course some managers want to get in on the situation because it puts them in a perceived stronger position in the company if their team is at the center of everything.
> You couldn’t use GitHub, Slack, or even our cloud platform without first learning how to navigate all of the custom tools and bots that had been put together to gate access to everything and make it work.
First time in a really big org and I can see this as well. The worst part is trying to tie someone down to explain how to use their custom tool or bot or even entire systems. How do I use that custom BI tool that you setup ... oh no-one wants to even send me an email reply when I ask a simple question about these things.
The way most stuff gets done in these orgs is various maverick people who find some way to work around all this crap. The problem is you have to have political clout to do that most employees don't have that.
I think these "meta-tool" are initially well intentioned but as you say they become empire building tools.
Worst still is that the teams that build them often leave or are disbanded. Then no one is responsible and no one wants to touch them and they sit in this weird limbo state.
> My opinion is that once an organization is a certain size, everything really needs to be written down and easily accessible. I shouldn't have to regularly ask people how to do basic things, it should be on a wiki. If it's complicated, it should be in a training video, or a user manual.
This %100. Automate all the things, but for any part of the process that cannot be automated/scripted, write it down. And don't just put it in some random Google Doc or Sharepoint where it is lost forever in the ether. Put it in a README that lives with the code or have a shared Wiki for the team. It need to be somewhere that is generally available, searchable, version controlled, and easy to update.
Even if it's all documented with a README, with container images and Ansible playbooks or whatever to make it all happen… still people will be complaining that it's oh so complex and that's not how we did it in my previous job and what about secret management, or load scaling, or full disk encryption, or how would this be deployed to a moon-based server, or whatever they can think of how the probably less-than-average crap you've built isn't maximally convenient for them.
So, even if you have everything 100% automated, most people will look at that and conclude that your automation is complex legacy bullshit and you should have automated in some other way.
I second this emotion. We have spent years and countless hours investing in documentation and automation as we re-engineered a very large legacy application into cloud based technology (AWS). The application and supporting CI/CD pipeline is far better documented and supported than most and all of the underlying technology is within 5 years current. There are video based tutorials on nearly every aspect of the platform and machine images to accelerate development environment setup. Yet still, people new to the development pipeline will hand wring over "tribal knowledge" and "deployment complexity". News flash, anything constructed to support hundreds to thousands of business processes and millions of customers is more often than not going to be complex. Sometimes you just have to roll up your sleeves and try to improve the trail for those coming behind you.
Seriously. I hate "video tutorials" on how to do technical stuff. I read faster than videos can explain stuff, and with text I can go back and forth to the stuff I need without trying to forward and reverse a video to a certain time.
The feedback is totally fair. What we do is conduct live "learning sessions" with experts in aspects of our implementation that go through tutorials on specific technical aspects of the platforms. These learning sessions are recorded and referenced next to the text based documentation that complements inline comments in the code. They are not a replacement for the text based documentation. Think of them as equivalent to various YouTube videos you might reference when learning how to do something. You might read the particulars in a piece of documentation but then also watch a walk-through of a specific piece of technology if you find that helpful.
I will say that things like secret management and FDE are likely policies that people are forced to follow and not things they directly want to implement.
Write it down even if it can be automated. And make sure the documentation is also comprehensible to people who don't already know how the system works.
Otherwise you're setting your company up for a miniature re-enactment of the Butlerian Jihad at some point in the future.
Note that I'm not saying we shouldn't do as best as we can with documentation, clean code, etc, BUT:
In the open source world, I've developed a large low quality codebase that is very complex from when I was less experienced. This project has gotten plenty of contributions over the years, some from less experienced and some from more experienced.
The experienced developers know how to get around the codebase, but the lesser experienced ones tend to complain about quality. I see this in the workplace as well.
I had this exact same issue when I was less experienced. New codebases was very difficult to understand, but now that I've been through a lot of them in various languages and quality, it's not as bad as it used to be.
I guess the argument here from the business point of view is that we write code for the less experienced? In a way this makes sense, but paradoxically some complex codebases that I thought was messy in the past have become more elegant today as I've gained more experience.
It could be that the more experienced developers are just burnt out in trying to give that kind of feedback, and instead just grit their teeth and get through the code base as they need.
Meanwhile the newer, less experienced developers probably still have a bit of... let's say naive optimism, and try to give feedback more.
That could be the case for a job you get paid to do, but for open source there are people coming in to help because they like the solution and have ideas for new features or refactoring.
The inexperienced developers in my case have not contributed much, but rather complained in other channels. (it's game related, the community is on discord, in game, etc)
it is probably because the new devs know so much more and are able to identify and communicate problems in code that others have written.
write code for the center of the bell curve (at your organization). the bottom will never understand anything, the top understands it all. You need to make the majority in the middle be comfortable.
that means slowly bringing in new language features, as they become widely known and practiced.
That's an interesting point of view to explore. Is it worth more to attract a few highly capable developers or a lot of middle capable ones?
Your code practices will probably resonate differently on each of those groups, so you will probably have to choose. And I don't think there's a generic correct choice like you imply.
Also, by how much are people even capable of choosing the (required) expertise level of the code they create? I'm not sure we can deviate a lot from our natural level.
Good luck convincing organizations to invest in this + finding people to do it. I have the background to organize this (I'm actually doing this for my own, smaller organization right now just because the situation is driving me insane) and the main problems are:
1.) The people who can do this aren't going to do it for 30k or $10/hr. Properly solving this problem requires an understanding of tech and the development process, pedagogy/communication/instructional design, and information management. Lacking any one of those would result in a system that's an unusable vanity project. I have a couple of decades of small-shop coding experience, experience as an instructional designer at an Ivy, and graduate education in information management, but if you want me to use all of those it's going to cost you and companies are resistant to that. (See: How a lot of non tech product companies treat their IT teams since they don't generate revenue). Now imagine if the project were led by someone more qualified, which it should be for a company of your size.
2.) Most companies don't have a culture which would allow this to be done well. This is the sort of work which requires both a lot of honesty and a lot of careful planning. A lot of information ends up hidden or inaccessible due to people's egos, or executives not being able to handle the information so it's buried. People need to be honest about their workflows and what they don't understand, and they need to feel comfortable being honest about such things. This gets really messy. On the dev side, a common cultural issue is "I had to learn it, they should too" or the urge to make understanding the complexities into a shibboleth for the in-group.
So I agree with you, but it's unlikely to change soon in my opinion.
Can I ask how you got started in the field of instructional design? This is a field that I've not really heard much about until recently, and I'm curious how someone breaks into that field.
Unfortunately, I'm one of the old 'I fell into it because I had experience in both the field's components (tech and education)' stories: I've been coding (mostly but not exclusively front-end) since the 90s and been teaching techy things on and off about that long (I taught my first programming class in '99 when I was 11), and then I went and worked in libraries/studied how people learn outside of formal classroom contexts.
So I already had all the skills needed once the field started. I cheated.
If I were getting started now, my advice would be to remember that the human element and the tech element are of equal importance in Instructional Design. So you'd want to take stock of what skills you currently have and how best to a.) get the necessary knowledge you don't have and b.) take advantage of your particular skill set.
Since you're on HN, I'm assuming you're of a techy bent vs. an educational/people bent. So if you have any teaching/tutoring/etc experience, I would lean on that. If not, I would get some. You can do this by volunteering somewhere + doing some basic research. I highly recommend this since a large portion of instructional design (like most front-end things) is planning for all the weird things humans do when interacting with your stuff and, more importantly for instructional design specifically, how people who can't computer at ALL think. When doing ID, you're often designing for people who can't figure out how an email works and are taking a work training, for example.
Also since you're techy, I'd recommend spending some time with UI/UX and specifically focus on designing for different populations/audiences. From a tech perspective, your competing instructional designers are worst at the 'boring' things like accessibility guidelines, making sure things can run on terrible machines, coding fall-backs, etc. So a tech background is of great assistance as long as you communicate the problems it can help you avoid.
As for the actual 'how to get a job', I literally applied for my first job off of Indeed out of grad school and I'm a first-generation student so trust me that was not the most polished resume or CV.
Alan Kay has similar talks where he has some subtle condemnations of what the industry as a whole has devolved into. He uses terms like Cargo Cult and he calls out the wide spread hubris for not knowing and/or actively ignoring the history of the field.
Sounds like a lack of repeatability to me: complex tools, combined with lack of documentation, makes for a fairly unstable work environment.
It's for similar reason that I like to keep unreliable dependencies to a very strict minimum. I can rely on my compiler, my editor, my OS, and to a lesser extent a bunch of extremely popular libraries. But as soon as we get to internal tools & processes or obscure third party libraries, certainty goes downhill very quickly.
As somebody who has been writing software for two decades the most important ingredient for me is maturity. I am not going to leave the employment I currently have if signals of maturity are weak.
More money does not compensate for this. I thought it would when I interviewing a few months ago (50% salary increase). I was wrong.
It's a problem of the incentives we've setup. We reward engineers for building things. Promotions, pay raises, etc. for engineers are typically based on impact and technical complexity, not how good their documentation was. I've been at a few places that handwave at such things in their level expectations or skills matrix or whatever, but having been in promo discussions at a variety of medium and large companies it always comes down to what was shipped.
Problem is, at mature companies there aren't enough greenfield problems to match the large number of engineers who are looking to climb the ladder. So stuff is rewritten, then rewritten again since nobody understands the rewrite, and so on. Managers kind of look the other way because retention and the ecosystem becomes messier and messier over time as promoted folks leave and new folks come in that need to be promoted.
This is the world of professional software development at pretty much every company not a startup.
I admit I quickly searched my company directory to see if you work where I do :)
The article mentions 3 things engineers care about: Technology, Intellection and Stability. Perhaps your pain fits into the 3rd category (if extrapolate a little).
If so, ironically, the first 2 at scale is what causes the lack of the 3rd.
When you make wider roads, the traffic will get worse, not better. Perhaps it's similar technology organizations. It's almost inevitable.
Anecdotally Amazon figured this stuff out by mandating well defined organizational boundaries (kind of like solid white dividers on some section of the highway, eh?) and by making each team responsible for its own developer infrastructure. It seems wasteful at first, but maybe less so at scale. Maybe someone working there can confirm/deny whether this is the case.
I think you are touching on the right problem but your solution seems a bit more on the idealistic rather than realistic side.
I've had this conversation before where documentation is proposed as a silver procedural bullet and it never works. Documentation gets stale and eventually out of date. Do you really want to be in a position where you have to /recompile/ all of those documentation/training video/user manual materials? Unless you're selling it, probably not.
The solution you are looking for is not documentation but automation and training. The things which can be automated to make the process closer to obvious should absolutely be automated. The things which are intrinsically more challenging and can't be solved through automation should be covered through training -- and not a "training video" but a real set of sessions where someone (likely your manager or a tech lead responsible for ensuring clean consumption of their modules) is walking you through the right way to do things and leaving time for questions.
I say this having worked at a place that touted a documentation centric culture at the level of organizational scale you suggested. If you're doing anything remotely challenging, documentation only gets you to the starting line. It doesn't get you to being useful and autonomous.
Corollary: the documentation must be written to speak to the stupidest person in your team/company who you expect to use the product it describes. Otherwise, you may end up with a documented system that you can’t use or fix.
Fortunately, that’s often me (a supervisor), so I get to be self-deprecating when conveying this requirement.
I also find that hypothetical "interns" are great for this. Something about "this person without a degree, who probably hasn't been working for very long, who doesn't know your organization or who to ask, and is probably very scared of looking or sounding stupid."
It doesn't necessarily imply or require stupidity, but in my experience on both sides of it (writing docs now, and having been that intern), they actually make pretty great litmus tests for documentation and how accessible organizational knowledge is.
When I write process/operating docs, I write it for the person who is on call, at 02:00 Sunday morning, after overindulging in alcohol Friday night. I don't assume stupid, just not firing on all cylinders due to being half awake and distracted.
Some degree of complexity is intrinsic to the problem domain, but it's the incidental complexity that emerges as a thoughtless side-effects of other efforts that is the most annoying, especially when it compounds.
To flip your comment on it's head... Some of my most satisfying projects have been the ones that eliminated this type of complexity where I work, because they improved the quality of life of everyone I work with and gradually remove all but the necessary work. However because these things are usually difficult to isolate and deeply engrained, this is only usually possible once you've gained enough trust and autonomy, which I suppose makes it a hard sell for a new job.
Sounds like every multinational org with 100k+ emplyees, certainly this fits my own. Fun part is, there is no realistic way out of this. It only takes one obscure critical legacy app to add so much integration mess into whole ecosystem that nobody ever will be re-doing those.
Plus business won't put in the budget necessary for practically no change from their point of view.
I've worked at a 500 employee-company that had many of these issues, mostly from misguided attempts at copying the way FAANG worked without any regard for our own needs or scale. The entire code was a tangled mess of git submodules, transitive dependencies and the build system was contingent on a domain-specific language that was partially developed in-house and partially based on some unstable open source project, incredibly janky, and only two people got to see the sources for it or even knew how it really worked.
Dumpster fire doesn't even begin to describe the outcome.
There was always this strange spooky-leftpad-at-a-distance thing where stuff just kept inexplicably breaking, and nobody ever quite knew what had gone wrong, who to talk to, or when it was gonna get fixed.
Sounds like you are describing “institutional knowledge”. In addition to good documentation, an org needs to maintain employee retention, so you have people that know the what and why’s of all the automated processes you’re seeing.
Institutional knowledge is an okay thing, the problem is when it's passed down by oral tradition or actively kept secret unless you email exactly the right question to the right person.
Basically, my job requires using a lot of tools and technology and processes created by other people, but none of those tools are easy to use or well documented. In order to get stuff done you have to have a social network of people who know how to do the things you need to do, and know all the secret tricks. The right environment variables to set. The right arguments to pass to simulators. How to find the important bit of data buried webapp developed by people who apparently like to invent new words for old concepts. I get a lot of terse autogenerated emails that probably mean something to somebody, but not to me, and don't have human return addresses or really any way to discern the context of where they came from or why. A lot of tools use domain-specific configuration languages that are usually just python scripts that call a bunch of functions that are defined elsewhere and have no documentation.
These things might be reasonable in a startup with a dozen people, but we have over a hundred thousand. My opinion is that once an organization is a certain size, everything really needs to be written down and easily accessible. I shouldn't have to regularly ask people how to do basic things, it should be on a wiki. If it's complicated, it should be in a training video, or a user manual.