Where I work now, it's a shitshow. To a (technical) outsider who wasn't with the company when they built everything, the original requirements and constraints are not obvious. The solution was lazily built in an ad-hoc fashion, so requirements continuously emerged out of the need to work around the failings of some other foundational system that was badly implemented. Suddenly you're being asked for a zero latency relational database with 100% uptime and infinite storage, and you ask "why?". Somebody points to the fractal-like complexity of the existing system and says, "It's the only way to make it work properly". You ask for diagrams, design docs or operational docs. Someone hand-waves at the fractal monolith and says "Documentation as code, man".
In my list of mean things I'm going to insist on should I ever go crazy and start my own company, documentation will be just as if not more incentivized than the actual code.
I want design diagrams, users lists, documented decisions on how backups are expected to happen, how this is expected to scale, why we went with X pattern instead of Y, who asked for a given feature, then as a last measure start doing the brittle document bits like API reference n such.
The code has its own inertia and desirability, but if you don't push docs, they are looked down on even though they have proven value.
What are we, scientists building and designing a new system or children slapping mud into a play dough concrete mixer and moving on to our next mud pie? Write it down Mr supposed professional!
One of the things that has struck me as ironic for people who like to call themselves "engineers" is how resistant to documentation some software developers are. I understand and have experienced all the problems with documentation taking time and how easily it can get out of date, but when I look at what other engineers do when they need to modify a building or structure, they immediately go to the blueprints that tell them how the building is put together, where the structural support is, where the wiring and plumbing is, etc.
I guess those can just as easily suffer getting out of date, not updated with small changes, etc. but at least they provide a picture of how the thing was built in the first place, a picture that is still helpful for understanding.
I've found Lightweight Architecture Decision Records (as markdown docs in a repo with the code, or wherever makes sense) to explain the current landscape, options, decision, and foreseeable consequences. Keeping it really light makes it tolerable for people who don't like to write docs, though does need the team to insist on the doc for anything non trivial.
I also like using the Draw.io vscode extension to draw diagrams without having to export into a separate file or copy into the repo.
Back when I did these sorts of doc tasks for a prototyping team, I used to create BUML* using Visio. It was kind of hard but nowhere near as hard as using Rational's offering. The dev team liked and used them. I like the looks of PlantUML. Thanks for posting about it.
Careful with that wishlist. Design diagrams can quickly go out of sync with reality, and with no loop of responsibility to keep them up to date. In other words, brittle. Some artifacts are relatively timeless (like "Why we decided in 2018 to do X") but others are not.
This is indeed a big challenge for seniors hires. They are expected to understand the domain, product, and business context to create impact in little time.
I experienced this myself twice, failed miserably once and just about hung on second time. I've also seen quite a few senior ICs being let go within 4-6 months because they just couldn't get their head around the mess.
The obvious response of "document everything" hasn't been useful where I worked. Either company didn't embrace them or they got out of date in short time. I just don't know how to tackle it beyond putting in hard grunt work to understand the system.
> I just don't know how to tackle it beyond putting in hard grunt work to understand the system.
My team are simply replacing large chunks of infrastructure with properly built & documented infrastructure as code. If anyone has a problem, we're asking for a bake-off between this (sensible stuff) and that (wherever-the-hell mess you've got there).
Importantly, learn to modulate the level of technical detail at which you describe things and establish trust with your intended audience that your level of technical detail matches the nature of the problem. This gives your audience a clue that when you throw around jargon, it's because there's a subtlety in the implementation detail that breaks the abstraction and they need to care about it.
There's a difference between "This is a problem with our search indexing and we need to..." and "This a problem with Lucerne which is a search indexer. The tricky thing is, Lucerne implements search differently and because of that, ... and so we need to ... instead of ...".
You can't hide the detail with a wave of the hand, you can definitely overcommunicate detail that is unnecessary, but the art of it is finding a way to explain the bit that matters in a way that makes it clear to the users that you're eliding detail that isn't important, without misleading them.
There is a very fine example of this in cinema -- the senior partners meeting in Margin Call, where Zachary Quinto's character has to explain why the firm needs to sell all of a particular asset class:
That’s a great scene. For anyone who hasn’t seen the movie, I might recommend skipping the clip and watching the full film! If you’re on HN, odds are you would enjoy it, and it has an impressive cast.
as a security professional, there is nothing more frustrating than reading a report that completely misses the mark in terms of audience, and the overuse of industry jargon.
I learned a lot from my early career, first when selling computers, then when making websites for small businesses (with a side of IT). I also taught Office to senior women for a few weeks. It was a delightful experience.
When you deal with laymen, you get to see how complicated our world is to them. I like to see myself as their honest broker with this confusing world. This has proven a viable business strategy.
If this is not abundantly clear to you, consider how clarity shapes your interaction with lawyers, doctors and mechanics.
> If this is not abundantly clear to you, consider how clarity shapes your interaction with lawyers, doctors and mechanics.
I have a bunch of friends who are or have been mechanics and technicians. They, and others I have interacted with are actually quite good at explaining things in layman's terms. Doctors are quite similar in that regard. It's an important part of their job to do so. With lawyers I had fewer interactions, they tend to produce terrible texts (contracts, licences, ToCs etc.) but they can explain things typically well enough for one to understand their advice.
And going back to the article I think the problem statement is important. But the solution is only half-way there.
If you can afford to be less technical when interacting with others, then yes, do so. But given a large enough project and people you are building up knowledge about the thing your building and that needs terms (a mini language) that foster shared understanding. Those terms are often used across the code, data, UI, email, version control, chat and most importantly a spec or any document that describes the most important terms and their functionality.
All involved sides should be learning form each other and build up a common language. It's a two way street and it should be deliberate. It can be a small thing and still be super useful.
Mechanics, technicians, doctors and lawyers are jobs bridging between technical and non-technical. Mechanics and doctors needs to be able to talk to laymen, but mechanical engineers and chemists who design the parts/medicine don't need to do it. Similarly you have pure developers focusing on developing core parts, and bridging developers who focusing on delivering those parts to customers/users. Pure developers are still extremely important and a viable career path that pays well, you can't say that it is wrong to focus on that part.
I submit that you will always interface with people who are not purely technical, no matter how technical your role. But it is in the most technical roles that it's hardest to learn how to match your language to a given audience (for lack of practice/opportunities), so I actually think these are the groups that need to consciously work on developing this skill the most.
> I submit that you will always interface with people who are not purely technical, no matter how technical your role.
This is provably false though, I've worked in jobs where entire large teams never talked to non-technical people.
What you maybe meant is that you always talk to people less technical than you, which is true, but that is a very different statement. For example, when I worked on developer tooling at Google the stakeholders were all developers, the director was a developer, the directors for the orgs we worked with were developers, the product managers were former developers etc. There was just no non-technical people in sight. But you still need to talk to people who are less technical than you, that is still true, but it isn't true that all jobs needs to be able to talk to non-technical people.
I think many misses all the people who work in the background because you don't see or talk to them, but they still exist.
That's fair. I concede that there are jobs that in no part rely on communicating with non-technical people. But I still believe you will find it beneficial to be able to explain your work to non-technical audiences. Your family, your lawyer, or a future hiring manager will all value it.
All I did was work on/design math/algorithm libraries. I can of course explain that I write code, and which parts of Google used it, but I can't explain anything I produced to non-technical people since there is nothing left when you removed the technical details.
I also worked on server message routing. I can explain that it is basically like the internet, ie explain why my job is important, but explaining any of my projects to a layperson wouldn't be possible without teaching the layperson a lot of technical skills.
Many moons ago I worked in a briefly-successful UK "dot com" integrator, and then took a break from work for personal reasons.
When I came back, I rejoined in the design department, rather than return to a role in engineering, where I had been mostly front-end. (I described myself whimsically as a "pet engineer".)
What we realised then is that the design team needed an engineer on their side of the divide to act as a go-between with implementation, but also to translate requirements in both directions, explaining what each side thinks (as well as urging some respect for the designers' craft).
Nowadays this is reasonably commonplace but at that time it was pretty radical.
Technical teams often make the mistake of thinking that their knowledge, their language, and their problems are supersets of or at least the essence of the problems of the business. They are quite wrong.
I have a phone call with my stepmom most weekdays. Part of the call always involves discussing what we plan to do for the day. She’s very impressively technical about the things she’s interested in, but our areas of expertise have very little overlap. I find it rewarding for both of us, and a really good mental exercise to “explain it to my stepmom” and find we both share some understanding at the end of the conversation, and I know she does too when I’m hearing her goals and ideas.
Learning how to communicate with anyone is hard. But it’s very worthwhile if we can.
This was my telephone life with my Dad for thirty years, all of his later life and almost two thirds of my life, even well into his dementia (because his memories of his professional career were really untouched by it).
After only one month I already miss it enormously.
I am very glad you find these calls rewarding and I am certain she does too. I am going to have to find someone to fill this role in my own life again.
And yes -- navigating the line between the endings/beginnings bit, the loss (which it is), and tragedy (which it isn't) is difficult but this time around I am finding it easier.
One of the things I have already realised is that explaining-stuff-to-my-Dad is portable. I can do it in my head. And when I can do that without tears, I'll be able to add my Dad to any audience in the future, and hear his questions as well as theirs.
I’m terribly sorry for your loss. I very much appreciate your reply, and I hope you find the person you want/need in this role.
If I may be presumptuous as a stranger who’s grieved several special relationships to offer advice, please try to catch yourself if that pursuit/search feels like it’s looking for a substitute for your Dad the person. Whichever relationship like that comes next will be both familiar and unusual. It might still be worth pursuing even if it doesn’t feel right at first.
Back in my service desk days, we were encouraged to write and revisit SOPs in our downtime as it is and excellent way to pick up how things work, and how to write in a style that everyone is on board with.
The most effective part of that system was to get the older lady in accounts to run through some of the processes that required detail and rigor to see where things weren’t clear enough.
- What are the first principles of communication.
- Of what you want to say, what can they hear.
- The more refined (technical) your knowledge, the fewer people there are who can understand it.
- "Language is the interface for describing problems." This phrase makes me rather happy for some reason.
- Do you want to sound clever, or be clever. (It's easier to sound clever.)
- What are all the functions of using more technical language than necessary.
- Understanding what's relevant to another person is an advanced skill. In any context.
- Filtering technical knowledge into a relevant format for a listener to comprehend in real time is a skill that can be learnt.
- More people think they understand than actually do.
- There are infinite layers to understanding even the simplest thing.
- At what point do you tend to decide you've understood.
- Where does the feeling of 'understanding' come from.
> Filtering technical knowledge into a relevant format for a listener to comprehend in real time is a skill that can be learnt.
Sadly, not a skill most "scientific journalists" appear to have learned. There's a difference between "make understandable" and "dumb down to complete context-free drivel"[1].
And that's before the aforementioned "journalist" takes a single press release from a university PR department at face value rather than doing, well, journalism.
My understanding of what might be going on here is broken telephone with intent. A reporter gleans only a subset of information from a given body of research, then ends up reporting only on what portions they consider to be essential. The end result loses nuance and context.
I don’t think reporters want to be doing this, but society doesn’t incentivize serious reporting in of itself.
I find this to be true. I find that while I work with people who are perfectly capable of becoming experts in a given category, they protect their brains from having to hold unnecessary information that isn't relevant to their current course. This is a very important survival tactic in our field as one can get easily distracted.
I can count on one hand the number of people I could walk up to in a hallway with a random article and geek out for 3hrs--like a mental foodie. A rare profile indeed.
Well-put. I participated in a protracted comment thread several weeks ago about the use of 'number' in HTML input field 'type' attributes. The problem was inexperienced HTML writers using 'type=number' for phone numbers, order numbers, social security numbers, account numbers, etc. The resulting interface elements— e.g. increment/decrement— are designed for elements like quantities and are more harmful than helpful with those more common uses.
I argued that in general, people are perfectly correct in calling telephone numbers, order numbers, account numbers, social security numbers, etc. "numbers" regardless of how a computer handles them. I also argued that the purpose of HTML was to describe data rather than how it should be handled, and that argument is to describe formatting rather than a data type. I asserted that a general-use term like "number" was wrong for a field with such specific use cases obvious only to developers.
Personally, I think the shakiest part of my argument was asserting the purpose of that label. To my surprise, others only argued that labelling those other things 'numbers' was not accurate in general because computers didn't treat them like numbers, and supported the current label 'text.'
OED definition 3a for number:
> An arithmetical value assigned to something or someone, esp. to indicate position in a series, or for purposes of reference, identification, etc.
There is no definition for 'text' in the unabridged OED that describes anything other than words.
English is a descriptive language and software doesn't override that. Most people see a collection of numerals with punctuation and think "that's a number" and that's clearly how we use the term in regular language. "Order Number" and "Telephone Number" (3b for 'number' in the OED) are not colloquialisms. The most common uses for fields those developers would consider 'real numbers' — e.g. quantity— don't even have the word 'number' in the name.
I don't even expect most developers to intuitively recognize how these ingrained shorthands differ from the rest of the world, but we MUST NOT instinctively dismiss indicators that our perspective isn't representative. We're making the tools modern folks use to solve many of their problems and we stand to make their lives a lot worse by assuming our use cases, language, challenges, and perspectives are the same or more worth considering.
I always have trouble parsing the Seemingly Wrong Thing That I’m Redefining writing style, so I’m not sure my comment is germane.
It seems like OP is saying to communicate about technical matters in a way that is not obscured by jargon and distracting minutia. That is generally good advice, and has an ancillary benefit that explaining deeply technical matters in plain language usually deepens the explainer’s understanding.
There is a less charitable interpretation where this is just “I talk to the customers so the engineers don’t have to!” dreck, in which case, Be Less Click Thirsty.
My interpretation was that it was more of an encouragement to think about things at a higher level of abstraction rather thinking of implementation details, as is a common reflex for so many programmers. Being able to communicate at that higher level of abstraction is a consequence of first having trained yourself to think at that level.
Yeah it's an important skill. I knew an engineer that was about as smart as me in school. If there was a real stumper of a question on the exam, we'd be the only two to get it right. He was a hard worker. But that guy was incapable of discussing things at the 64,000 ft view, let alone the 30,000 ft or 10,000 ft. As a result, he had a really tough time working with anyone else, and the entire program was deeply focused on teams. You became like family with the other students by the end of the 2nd year. Your reputation in groups was incredibly important. This guy, he could be completely correct, and yet somehow get other smart engineering students to turn against him, including myself. No one could work with him. One instance of that still haunts me... It's really unusual that I don't listen to someone else and consider what they had to say, and yet I did exactly that on a really important project with that guy. He was completely correct about a very important and fundamental thing, and yet I just couldn't see it until it was too late. 10 years later, that still bothers me.
That lack of skill haunted him in his later career. The last I'd heard, he had gotten fired from a job with a company that didn't fire anybody. It was bizarre to watch someone that could think about such technical and difficult things effortlessly, yet be unable to reason about them (or at least communicate) with nearly any level of higher abstraction.
OP here - I think your interpretation (the former) is pretty spot on. I also think the less charitable interpretation is not _exactly_ wrong. The title and repetition of "Be Less Technical" are definitely not devoid of "click thirst" - but the content is intended to be more in line with "we need to find ways to talk to each other, irrespective of whether we talk to customers or compilers".
I'm flattered that the OP took an interest in my comment, and when I said "less" click-thirsty I hope I didn't come off too judgemental: whether we admit it or not we're all pretty well wired-up for the engagement dopamine hit at this point, including me and my comment.
Given that you've clarified the point you were making was the one I hoped: I am interested in hearing more from you and I would gently discourage that particular writing style. Your post could have been called, just for the sake of argument, "Work Technical, Speak in Plain Language" or something to that effect.
There is this, I'll say it, dysfunction, where certain folks in the software business are trying to create a (high-paying) career track that is adjacent to deeply technical stuff but not really touching it. That needs to be drowned in a bathtub.
Anyone smart enough to write an optimizing compiler is smart enough to explain how one works, at least in outline, to a layperson. There is no need for a middle-man layer of blubber between the people who need to know why to buy or not buy one, and the person who knows how to write one.
> Anyone smart enough to write an optimizing compiler is smart enough to explain how one works, at least in outline, to a layperson. There is no need for a middle-man layer of blubber between the people who need to know why to buy or not buy one, and the person who knows how to write one.
I don't think that conclusion follows from the premise. I could also mop the floor and clean the windows at work, but that doesn't mean that it would benefit the company overall. Similarly, just that engineers could in theory explain the thing they do to e.g. a customer does not mean that they should spend their time doing this. *
There's further nuance in that (in my experience) engineers tend to be, by default, not great at communicating at the right level with a lay-person (which is more or less the point of the article), and that hiring people to interface between e.g. customers and engineers comes with pitfalls and can go wrong (your point, I believe). I personally think it's best if someone who presents products to customers has a deep engineering background and has transitioned into their customer-facing role from there. But if you need to visit more customers to make more sales, hiring more sales people instead of drawing from your engineering department is probably a wise choice.
I say these things as an engineer in the trenches.
* To be clear, I have no intention of disparaging either job.
I mean to be clear, I'm not drawing a conclusion from a premise: I'm making an assertion, and in fairness, that assertion is trivially false by virtue of invoking words like "anyone" and phrases like "no need". Nothing exists `forall` what I said. I'm also aware that the assertion is a flashpoint for a lot of people and extremely controversial, even when you relax propositional logic enough to admit the trivial counter-examples (intelligence is clearly not some nice, neat scalar quantity).
Nonetheless I think that everyone knows what I'm saying: which is that they're are more than enough people who can both do deep technical work and wear clothes well and work a fucking powerpoint that the industry doesn't need to resort to employing nontechnical people in roles that require both, and that outside of certain verticals, someone who knows their shit but makes iffy eye contact or stutters is still a better person to put in front of the slide deck than a slick, charismatic figure with a dim grasp of the subject matter. It's nowhere near the either/or that it is so frequently presented as, and even when presented with that either/or choice I'll take the competent nerd unless I'm selling IBM z-series boxes to credit unions or something like that.
Given that OP is on the thread I'll leave it to them to clarify the point of the article, but I will point that my reference was to a classic parody of this whole "good with people" trope that was already darkly funny long before pervasive cloud services, the vastly increased prestige in software engineering roles, exploding FAANG engineer salaries, and all the other things that have people with the right look signing up for CS classes in droves [0].
> Though not a perfectly applicable example, we can see that the English language, due to its rules and formalization, does not have a single word that describes the complexity behind the feeling of “Schadenfreude”. This is an inherent constraint in the English language as it pertains to its translation to German.
Except English does have such a word and the author literally linked to its dictionary entry in an English dictionary.
OP here. I think it serves as a loanword, but I concede that linking to an _English_ dictionary can blur the point I was trying to make. Edited for clarity, thanks!
Contrived example does not serve the argument well, if someone is starting with "our users are complaining that our system is slow!", they could already do some legwork and check for themselves or check with users before dropping it directly on the engineer.
If someone goes to a surgeon he does not start with "I don't feel well, do something about it please", that what general practitioner is for.
I understand there are small companies where engineer is basically support as well, but for any bigger operation follow up question on "what part of system is slow" should be worked out on support level and provided with question to the engineer.
Very true. This is why I think 'Thing Explainer: Complicated Stuff in Simple Words' (Randall Munroe) is so brilliant. I think being able to communicate at the level your audience is an under-appreciated skill.
My advice: Practice explaining what you do to your grandma. Not all the time, mind you (she probably has other things to attend to), but it is incredibly effective at showing you how "zoomed in" you are in your work and where there is still a "translation mismatch".
I still regularly catch myself using words that I think are common or high-level enough, just to realize that they don't invoke nearly the same picture in a non-technical person as they do for me.
This is the kind of patronising attitude that will further the gap between engineers and product people.
Being able to articulate technical details with the right level of abstraction, and without "dumbing it down" is an essential skill when engaging with stakeholders of varying levels.
Agreed. When talking to a doctor, you expect to communicate in terms you understand, or at least have essential terms explained in a non-condescending manner. It doesn't matter if they know a technically correct term for something if it means nothing to you - you expect to be communicated with, not communicated to.
The same expectations carry across to most jobs in tech. It is rare that you work in isolation, so being able to communicate details without going over the head of the other person is an invaluable skill to master.
I agree with you... mostly. I do find it frustrating that almost all the effort is expected to be on the technical personnel. I don't care if you are a "business" person (aren't we all?), I don't care if your job is sales, or product management, if you deal with software all day, you should put the effort in to understand it.
There is an expectation that the technical person has to explain everything at 100 different levels of detail, depending on the composition of the people in the room. But there often isn't the reciprocal expectation that the non-technical people put some effort in. If you work with a technical subject and you can't understand it, past a certain point, that is on you.
It's your job to understand this stuff, do your fucking job.
Not sure where you are located, but I've lived in many places in the Midwest and Florida, and almost every doctor I have interacted with is fully capable of explaining things and does it well. This is not a once-in-a-lifetime thing, but a basic requirement. If your doctor isn't doing this, maybe you should ask more questions. If your doctor can't do this, find another one.
No its not. The commenter is right. There are schools that teach people how to transmit knowledge to other people. Not only it is not for everybody but even those that finish those schools usually suck.
You are missing one of the great untold truths of engineering: non-technical people can be just as brilliantly intelligent.
They just don't speak your language or have your experience.
You do not particularly need to dumb it down. You do need to think about which things they actually need to know, and provide some backstory that helps them contextualise it.
Get good at this and your life will be enormously better. Keep this attitude and you will find your world shrinking.
I agree wholeheartedly with this. I have lost count of the number of times I have found a solution to some problem after explaining some technical detail to a layman who then suggested something I wouldn't have thought of.
I don't really think of dumbing it down, more like distilling it to its true essence. To be able to do so requires even more skill and understanding than just enumerating the details. I always think of the Feynman anecdote where he talks about skipping chalk on a chalkboard.
I wonder how strong of a signal that is for a good engineer. There have always been people who've stood out as wanting to teach, wanting to mentor. Is it too much of my own bias to say that good engineers are good teachers?
I think that for example good designers are usually good teachers, so maybe.
Good design and good engineering explains itself; especially engineering that interfaces with other stuff. Well-designed things need less documentation.
Both, I think, require the same focus on clarity of intention as a good teacher.
> Talking technical stuff to non technical is an enormous pain. The levels of dumbing down is near endless.
It's rare that a non-technical person expect that they will be able to understand lots of technical details after one conversation. More likely, they aren't especially interested in technical details.
They likely want to talk at a high-level about requirements and development schedules. If a software developer is unable to communicate effectively with people who aren't software developers, that's a skill they should work on.
Lawyers, accountants, architects, and doctors, for instance, are expected to be able to speak with people from outside their profession. (I see wfme already mentioned doctors.)
> Not everyone has to be able to explain their product to the masses
That strikes me as unambitious. If software developers have earned a reputation for being unable to communicate effectively, that's unfortunate. The answer isn't to invent a whole new profession to fill the gap.
The only line of work I can think of that outsources communication with 'the masses' is science. I suppose there's an analogy between scientist/science communicator and engineer/marketer, but I imagine science communicators tend to be more technically literate.
> Lawyers, accountants, architects, and doctors, for instance, are expected to be able to speak with people from outside their profession. (I see wfme already mentioned doctors.)
Those are frontline positions working directly with laymen though. So while doctors needs to be able to talk to laymen, the chemists working in medicine factories don't. The problem here is that we have the same title for frontline and backline developers, frontline developers are doctors, they know a bit about chemistry and can prescribe and implement treatments. However there is no reason for a developer optimizing database engine queries to be able to communicate their work to laymen, as the entirety of their work are technical details no layman would care about, they are akin to the chemists working in medicine plants.
People will continue to talk past each other as long as we have the same word for those two jobs. Developers who double as product managers and work directly with clients says that technical skills hardly matters and you should be a product manager first and foremost, which is fine but they shouldn't tell pure developers that it is wrong to focus on the technical part since they don't do the same job.
> So while doctors needs to be able to talk to laymen, the chemists working in medicine factories don't.
But they for sure need to talk to lawyers, accountants and doctors occasionally. All of those (especially the doctors /s) are laymen when it comes to chemistry.
You have frontline and backline chemists as well. Some chemists needs to be able to talk to less technical jobs, but other chemists specializes on improving the process or other technical skills.
So it isn't laymen/specialists, you have many many layers with people dumbing it down a bit in every step. Telling the specialists at the bottom of those layers that they need to be able to talk to the top of the layers is just nonsense. You need to be able to talk to people who are less technical than you, and to people who are more technical than you, so the layer above and below you, but that is it. It can help to be able to bridge more layers, but it isn't that important.
The problem with programming is that almost all those layers have the same name: software engineer.
