Consider your (multiple!) audiences

I’ve been spending a lot of time helping colleagues with communications lately, and one of the refrains I keep repeating is “consider your audience!”

For any given project you’ve worked on, you may need to be able to talk about your work in many different formats. Non-exhaustively, these might include:

  • Working documentation for colleagues within your team, familiar with all the context and able to find and integrate other documentation
  • A detailed report for other experts outside your team, showing all your work
  • A short technical report, also for other experts, but without all the steps shown
  • A one-page executive summary, geared towards decision-makers who are in that fuzzy “informed but not fully expert” zone
  • A less-technical essay in more informal language, i.e. the “blog post” format
  • A single paragraph summarizing key results
  • A 30-60 minute presentation
  • A 5-minute presentation
  • A single bullet point that can go in your resume

Each of these formats is pitched at different audiences — people who have different levels of background knowledge, need different information about the project, and who are willing to spend different amounts of time reading your work. Some formats might work for multiple audiences, but a lot of the time you need to use a different format when the audience changes. IMO there is no such thing as a format that works for everyone!

A common trap I see engineers fall into is thinking that the first version, the detailed technical report, is the only document they need. And that all the others can be produced by just copy-pasting from the detailed report. To some extent that can be a starting point, but each of these different communication formats does need to be tailored to the people you expect to read it!

I also see folks forget that some audiences will not have time for a detailed report. If you’re communicating with a less expert audience, they are almost always going to be unwilling or unable to read a 20 page doc… or even a 5 page doc. These audiences need their own format because you need to be able to provide information at the right page.

Over time, and especially as you get more senior, you will likely need to be at least reasonably good at all of these. In my current role, managing a fairly high-level engineering team, I often need to be able to write all of these for any given project.

Because it’s 2025, many folks will suggest “just use an LLM translate between formats!” That’s not necessarily a bad approach, at least when you’re going from a more detailed document to a less detailed one. I’ve seen LLMs produce some decent executive summaries. But it’s really important to remember that LLMs are just text generators, not experts — you are the one who actually understands your project!

LLMs will also cheerfully invent information, so you can’t trust them to fill in details starting from a summary. (This seems like it should be obvious, but I have absolutely seen people try to use an LLM to produce a detailed doc from a summary — that direction doesn’t work!)

The HPC cluster as a reflection of values

Yesterday while I was cooking dinner, I happened to re-watch Bryan Cantrill’s talk on “Platform as a Reflection of Values“. (I watch a lot tech talks while cooking or baking — I often have trouble focusing on a video unless I’m doing something with my hands, but if I know a recipe well I can often make it on autopilot.)

If you haven’t watched this talk before, I encourage checking it out. Cantrill gave it in part to talk about why the node.js community and Joyent didn’t work well together, but I thought he had some good insights into how values get built into a technical artifact itself, as well as how the community around those artifacts will prioritize certain values.

While I was watching the talk (and chopping some vegetables), I started thinking about what values are most important in the “HPC cluster platform”.

Continue reading

The Practicing Stoic, by Ward Farnsworth

Over the years I’ve read a number of different books on stoic philosophy, including some of the “modern Stoic influencers” like Ryan Holiday as well as a few translations of older philosophers like Marcus Aurelius. While I’d hardly call myself a follower of the philosophy, I do think it includes some helpful ideas, and it’s occasionally been a useful lens for dealing with some problem I’ve been dealing with.

I struggled with both sets of writing, however, for different reasons. The modern writers often made me roll my eyes, often clearly pitching at entrepreneurs and CEOs, and billing an ancient philosophy as a life hack. The work of the ancients, I found more interesting, but difficult to contextualize and navigate.

Continue reading

first dog walk of 2024

Some personal themes for 2023

Good riddance, 2022

This started out as me trying to write a “year in review” post, but to be honest I don’t have it in me. 2022 was a pretty difficult year for me, and I don’t terribly want to relive any part of it. Various family health issues loom large in that, but a ton of things went wrong.

Instead of looking back at all that, I want to spend some time thinking about how I want the New Year to go. Not in the form of specific goals, though I certainly have those (e.g., I’d love to get in more practice time at curling, and get a better grasp of programming in Rust). But this post is about some general themes I want to try and keep in mind moving forward.

Continue reading

Adam’s weekly update, 2022-12-04

What’s new

This week was really intense from a work perspective. Not “bad intense”, but the kind of week where every day was spent with such a level of focus, that at 5 PM or so I found myself staring off into space and forgetting words. I think I got some good things accomplished, but my brain also felt like mush by the time the weekend came.

Continue reading