Be Less Technical
sequential.dev
sequential.dev
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!
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.
Most engineers find them useful and not too much of a headache to write.
* Bastardized Universal Markup Language.
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 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.
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).
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:
https://www.youtube.com/watch?v=Hhy7JUinlu0
One day I will use the line Jeremy Irons uses in this clip. I don't want to spoil it by quoting it.
I initially watched it because Stanley Tucci is in it ... I stayed for the drama, and then Jeremy Irons stole it.
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.
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.
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.
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.
Learning how to communicate with anyone is hard. But it’s very worthwhile if we can.
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.
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.
It sounds like you are steadily strolling the road of healthy grieving, I'm sure he would be proud.
Keep your head above the water my friend.
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.
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.
- 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.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.
[1]: or maybe this is just https://xkcd.com/2501 on my behalf
I don’t think reporters want to be doing this, but society doesn’t incentivize serious reporting in of itself.
So you start at the level you expect the person to understand but you often have to go few levels lower (simplier).
I understand its needed for laymen, as in this saying “if you cannot explain something simple enough - you dont understand it well enough”.
Tho I often find myself explaining stuff the same way to experts in the field :)
Which makes me realize -> real experts are extremely rare.
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.
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.
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.
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.
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.
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.
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].
Except English does have such a word and the author literally linked to its dictionary entry in an English dictionary.
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.
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.
Talking with people is your interface to the rest of the world. If they don't understand you, then you're lost.
The levels of dumbing down is near endless.
Not everyone has to be able to explain their product to the masses, let someone else have that job.
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.
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.
Coming out of doctor that explained things to you is once-in-life event.
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.
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.
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.
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.
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.
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.
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.