Hacker Newsnew | past | comments | ask | show | jobs | submitlogin
Writing for Engineers (heinrichhartmann.com)
245 points by isomorphy on April 30, 2022 | hide | past | favorite | 37 comments


I agree with this perspective of the world (that senior+ software engineers need to be able to express themselves more fluently to be able to be impactful) but… just as a thought experiment, I wish it didn’t have to be that way. Writing is hard and not much fun (to me). Building systems that do something is hard but its a lot of fun. I just want to spend most of my time doing the latter. I just don’t give a fuck about impact or convincing others to work on my idea. If you are building something cool, show a little bit of it to me, and I like what I see, I would love to be able to drop everything else and work with you to complete it. Or if I think of some automation to reduce toil, I just wanna go tinker without having to think it through too much. If I run into constraints when building it, so be it, its a learning experience, but even failing is fun.

Obviously a rant. I just didn’t become a software engineer to be a good writer. I always wanted to build first and learn the constraints through mucking around rather than giving it so much thought before a single line of code is written.


> I just want to spend most of my time doing the latter. I just don’t give a fuck about impact or convincing others to work on my idea.

SDE 2 is a career position at Amazon — and it sounds like that’s what you want: to stay at that level, but working as the “point man” on increasingly important technical systems.

I would say that SDE 3 (senior) and SDE 4 (principal) are fundamentally political — you’re responsible for aligning the technical vision between teams and across whole organizations, as well as training SDE 1s and SDE 2s. You’re going to need to communicate, a lot, to do that.

Those roles aren’t management, but you’re also not an IC at SDE 3/4 the same way you’re an IC at SDE 1/2.

I think it’s okay to turn down promotions you don’t want.


If you are unusually good at being an SDE 2, there's not really a way to leverage that into pay or recognition or harder projects. Until you get the promo you will just be doing the same borderline-menial work any SDE 2 can do, a fungible story points resource. Although it's great that the engineering IC ladder provides an alternative path to people management, there is no alternative path to being a professional meeting-talker. We do not allow unusually capable individuals to write code that the median engineer couldn't write (because then the median engineer definitely couldn't maintain it). Instead we ask them to supervise and direct the work of the median engineers.

I actually think the best way to leverage mostly-solo intellectual work into business results and recognition might be data science. Models and analyses are allowed to be arbitrarily sophisticated and as long as the rest of the org understands the inputs/outputs/performance characteristics, they're content to treat the internals as black box. So data scientists can really go all out intellectually on their technical artifacts in a way that engineers can't.


Big tech has some specialized, high level/pay roles where someone can be successful just by being an excellent engineer, even with average communication skills. I've seen these in areas such as Compilers and Operating Systems Kernels, for instance. These jobs are, however, highly specialized and require extraordinary and domain-specific technical skills.


> I just don’t give a fuck about impact or convincing others to work on my idea.

Then you're talking about a hobby project.

/seinfeld Not that there's anything wrong with that!


I think this is mostly an organizational constraint. Having a lot of people going off doing whatever they want and not communicating about it sounds like a nightmare in a large organization.

Smaller companies probably have less of this organizational overhead.

> I just don’t give a fuck about impact or convincing others to work on my idea

I'm curious what you think a Senior+ role should entail in your ideal world. I'm not sure how you can get away from impact, since otherwise I'd perceive that as authority without responsibility.


> I'm curious what you think a Senior+ role should entail in your ideal world. I'm not sure how you can get away from impact, since otherwise I'd perceive that as authority without responsibility.

The technical expertise Ive gained over the years makes me pretty confident of executing on building complex systems that a younger me probably couldn’t have done. So it feels like a waste to me that Im not leveraging that experience to make more things but instead writing proposals and debating them with other senior engineers.


What I did was just build a lot of prototypes and then show those prototypes. It is very hard for people to say that something wont work when you have can show it working right there in the presentation.

You can put that prototyping work under "making presentations and documents in preparation for design discussions", because that is exactly why you prototype. Discussions gets much easier when you are well prepared, so when someone asks about performance you can show them benchmarks, if someone asks about alternatives you can show the difference in benchmarks and code complexity etc. A few hours coding can save weeks of meetings discussing these things.


> Having a lot of people going off doing whatever they want and not communicating about it sounds like a nightmare in a large organization.

Why? As long as what they do doesn't interfere with others work why does it matter if they don't communicate everything immediately, rather than at a meeting at a later date? If they don't deliver anything useful you put them on a PIP and ultimately fire them, just like everybody else, I don't really see what changes here.


Disclaimer: this is from the perspective of someone who is NOT a Senior engineer.

My experience so far has been that there is very little work in a large organization that doesn't affect multiple teams at some point.

So if you're a Senior+ engineer building a complex system, it's highly likely to impact a lot of other people in the company. Building something like that without getting impacted teams onboard with the idea seems like a recipe for organizational strife.

Another thing that comes to mind is organizational goals. If the company has high level goals they want to achieve, having people (Esp very Senior people) working on multiple things unrelated to those goals doesn't seem conducive to success.

Also, the more senior you are the more visible you tend to be. So what you work on is probably going to be noticed more. I know that I would find it weird if I found out a Staff or Senior Staff engineer was off working on random things instead of leading an important project.

I definitely think Senior+ people should have some freedom, but absolute freedom doesn't seem like a good idea for anyone. When you're at a certain level what you do affects way more people than just yourself. Titles have a lot of weight to other people.


Tight collaboration doesn't scale all that well though. From what I've seen, once a team has built a product/service they now start to put up red tape around it and make changes harder and harder the longer it exists. In other words, teams starts accumulating bureaucratic debt, it is very similar to technical debt. It is great to have that for the sake of stability, but the agility/creativity from more individual work is also great.

There is no reason you can just have one or the other, if you already have a lot of tight collaboration then you probably miss out on many potential changes that are too disruptive to be politically feasible. But you are right that you can't have only individual work, organizations needs tightly collaborating teams to be an organization.


I completely agree with everything you said :).


I actually like writing a lot, but I still think that often post-senior roles downplay the importance of still being an actively involved in building things.

There's a lot I have gained by having the chance go work on systems built by brilliant people. That kind of learning just can't be captured by prose. Some learning and knowledge sharing can only be done through the software itself.

People ultimately want those post-senior roles not so that they can stop coding, but so they can have more autonomy over what they code. That mismatch between IC and management expectations.


I enjoyed learning your perspective. This could only have happened because you wrote about it in your comment.


> Know your audience

This point is something that I notice in a lot of meetings. Some of the engineers I work with are long winded and tend to over-explain concepts/issues to non-engineering folks. I try to send a direct message during the meeting (now and then) to try and reel them in a little by explaining that the non-engineering folks don’t need those details and that a what they are really asking for is a summary of the key points of the concept/issue under discussion, but it’s not always well received.


That, and even if it is the right audience, know when to save your topic for another context.

I used to work with someone who, as a team meeting was wrapping up, was prone to interrupting everyone’s departure with a question that could easily have been asked on Slack.


> “and even if it is the right audience, know when to save your topic for another context.”

Yeah I agree with this as well


I tend to under explain using lots of phrases like "it gets pretty mathy" as an excuse for hand waving details away. Most of the time I think I am doing the audience a favour but for the most part it seems like they actually want an explanation that they won't understand. I think lack of understanding gives them confidence that the implementation is as technical as they imagine it to be, and that I am actually engineering and not just talking bullshit.

Going forward I think I'll prefer to be more technical for the self advancement.


Empathy is its own little rabbit hole.

Suggest reading a negotiation book like Never Split the Difference or 3D Negotiation.

These books spend hundreds of pages describing techniques to jog your ability to put yourself in the other person's shoes.

Endlessly bring up the major point, talking about how human beings see the world through rose tinted spectacles. Negotiation is about gathering information to make an offer the other person will accept.

Thinking about the point of view of the other person is difficult, mentally intensive work.

Most folk I need can do it. Many have just... fallen out of the habit.


Never Split the Difference is a good read. I haven’t heard of 3D Negotiation.

> Thinking about the point of view of the other person is difficult, mentally intensive work.

That’s true


I’m definitely guilty of this one, and have been working on improving it due to feedback from a teammate. In my case it was very much appreciated :)


I’m sure we’ve all been guilty of this now and again. Glad to hear that it’s possible for people to take this kind of feedback and put it to use.


Lots of good advice in this post.

I also find the 10 tips for clear writing at the following link very helpful - it overlaps with some of the advice in the post above - and includes some additional suggestions:

https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/

You don't need to listen to the podcast at the top of the page above (unless you want to). Instead, scroll down the page and you'll find a short description of each of the following tips.

1. Establish ‘The Point’

2. Write it like you’d say it

3. Don’t try to sound clever

4. Show the thing

5. Know that you are not your writing

6. Share your work

7. Read (poetry in particular)

8. Never start with a blank page

9. Know when enough is enough

10. Stay human


If I were editing the article being discussed, I think I’d suggest getting rid of the first three introductory paragraphs. It’s okay to assume the reader already agrees writing is important.


and the last two words of the title


> your are not ready

heh. Ironic.

Everyone makes silly mistakes. Just mildly funnier when it happens in an article about "how to writes good"

While we're on topic of annoying besides-the-point HN pedantry, I find the use of blockquotes in this article to be distracting. What are they quoting? They seem to be more of an aside than an actual quote?


Sometimes I'll use block quotes like that too. Newer software generally calls them "admonitions" to make their usage more ambiguous.


I vastly prefer Larry McEnerney’s lecture The Craft of Writing Effectively:

https://www.youtube.com/watch?v=vtIzMaLkCaM

In particular, he disagrees with this article about outlines.


This is one of the best – maybe the best – videos I've seen on effective writing. I rewatch it every couple months.


In which bit of the lecture does he talk about outlines?


Outlines are mentioned about six minutes into the talk, but it is, IMHO, heavy with context, so I strongly suggest you simply watch it from the beginning.


I agree with the author's perspective. Writing is the one skill I am working hard to improve. Since I hit senior positions, it has been a superpower, mainly in a remote culture. Sharing findings and experiments internally with concise texts will give you excellent visibility in the company you work for.


This post is a pearl! I love writing and I think that I'm good at it. However, I still have to learn and this post gives a sound structure. The point I'm struggling the most is to help my teammates growing their writing skills and to make them love writing. I will definitely recommend them this post!


I have a curious question. How to get started? When I am working, I cannot take notes. If I take notes, I won't be working and I will be derailed from my work.

When I am out of work, I forget the details of what I did because I lose the flow of it.

So it's a very confounding situation. I am in a ever growing battle between write or work. Can you advice on how to express what we learnt?

I will be very appreciative of it. Thank you so much!


Cool post, is there an RSS feed?


Well the first sentence is, if not wrong, at least exceedingly awkward:

Writing is key to have impact in large organizations.

Maybe "Writing is the key to having an impact in large organizations."


too exhausted to write out blogs... just being honest




Consider applying for YC's Summer 2026 batch! Applications are open till May 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: