Illegible software engineering

I enjoyed Karl Yang’s essay on illegible work and wanted to riff on it a little, specifically from the lens of software engineering at larger technical companies. 1

There are two failure modes that I’ve seen most often:

  • A talented and proactively-minded software engineer at a large company feels that the most important and highest-leverage work they could be doing is not what they’re being “graded on” by the performance review process;
  • A single engineer on a high-functioning team is saddled with important work (updating docs and runbooks; meeting with users or core dependencies; onboarding mentorship; etc.) that isn’t evaluated in the performance review process.

I think the latter of these two cases is a much more solved problem through a combination of tooling and brag docs, which I’ll be sure to write about later.

The former is trickier, and one I can empathize with: the most rewarding (both personally and financially) projects I’ve had in my career involved doing work that was mostly unrelated to my team’s success criteria.

I’d recommend two principles when setting out on this kind of work:

  • Just because it’s not legible doesn’t mean you can’t leave a paper trail. If it’s hard to state the falsifiability of your work in quantitative terms, then try qualitatively. Any serious and nebulous project that’s worth your investment should also have an essay outlining why the work is important, what level of time & energy you expect it requires, and who should be invested in the outcome. Having artifacts to refer back to help build confidence up the org chain and keep you intellectually honest.
  • Foster sponsorships and build trust. The harder the work is to visualize in a metrics deck, the more its success relies on the cooperation of your team, your stakeholders, and your reporting chain. The most successful folks I know who consistently do weird but incredibly high-impact work do so because they have senior leaders who trust them to go off into the wilderness for six weeks and come back with fruit. 2

If you can neither coherently state the rationale & expected return on your work’s investment nor find people who believe in it, something is Wrong. It’s hard to say what that Wrong is without context — it might be that your workstream really isn’t the right area of investment, it might be that your organization is overly risk averse — and I hesitate to prescribe in broad strokes.


  1. Why larger technical companies in particular? Because legibility as a concept doesn’t really come into play until you’re in the thousands of employees range.

  2. Can’t be understated how much time is a key role here — being in an organization long enough to amass deep knowledge not just of the system at hand but of your fellow inhabitants is the single easiest lever you have (though it requires patience.)

Want to read more?
Found an issue on this page? Let me know.
© 2022 Justin Duke • You deserve a high five.