Sunny

← All weeks

What I’ve been reading (W47, 2022)

Why should a software engineer care about docs · Criticizing Computers

Why should a software engineer care about docs

  • One of the hard problems in software engineering is getting multiple people to understand some technical aspect, like the actual problem being solved or a proposed solution. This is ostensibly the only real goal of technical writing.
  • The hardest problem in software engineering is getting the appropriate information into the heads of the people who need to have that information to do their work effectively.
  • You might have an impression that you understand something well, but that sense of clarity is often an illusion. When you go to explicitly capture your understanding in a document, you discover that you didn’t understand things as well as you thought. There’s nowhere to hide in your document.
  • Writing out a complete example will force you to confront the gaps in your understanding.

Criticizing Computers

  • Good hardware is masking really bad software. The processors in our laptops are over 1,000 times faster than they were thirty years ago but the programs don’t run 1,000 times faster
  • All the bad code is piling up, and we don’t know how to get rid of it. We have more memory than we know what to do with. Rather than natural selection, we have a regime of hoarding. All the bad code can live on to torment and confuse the programmers of the future.
  • Software is not technology. It is ideology.

Don’t hide things that didn’t go perfectly

  • Being honest about challenges has several benefits
  • Helps others learn — by not talking about issues, you deny others the chance to avoid them in the first place and learn.
  • It makes you more credible — people know there are always challenges, and overly rosy discussions will set off people’s BS detectors.
  • It is just more interesting — a bit of drama and vulnerability is much more interesting than “everything went great, and we did the stuff”. You don’t want to overdo it, but you can make discussions, reports, evaluations, etc., a little less mind-numbing.

The unreasonable effectiveness of simple HTML

  • There’s a lot of crappy browsers everywhere (TVs / cars / old devices). Not everyone has a big monitor, a multi-core CPU burning through the teraflops, or a broadband connection.
  • If you are building information / public services, build things that can work on rubbish browsers.
  • Plain HTML works. A small bit of simple CSS will make it look decent. JavaScript is probably unnecessary - but it can be used to progressively enhance stuff. Add alt text to images so people paying per MB can understand what the images are for (and, you know, accessibility).
  • Go sit in an uncomfortable chair, in an uncomfortable location, and stare at an uncomfortably small screen with an outdated web browser. How easy is it to use the websites you’ve created?

Good Product Strategy, Bad Product Strategy

  • Bad product strategy either ignores customer segmentation or attempts to cater to all customer segments.
  • Bad product strategy either downplays the competition or ignores these factors altogether.
  • Bad product strategy presents a laundry list of priorities or “strategic goals” to tackle all customer needs.
  • Bad product strategy defaults to one of these stances without a rigorous assessment of options and industry trends.
  • Bad product strategy eschews trade-offs and tries to be “all things to all people”.
  • Bad product strategy either ignores these advantages or overestimates their potential impact on the product’s success.
  • Bad product strategy relies on factors that might be a current source of advantage but are over time, more susceptible to getting neutralized by the competition.
  • Bad product strategy makes proclamations about wanting to be “the best”, “most delightful”, “world-class”, etc., without adequately specifying the concrete product choices that will make it so.
  • Bad product strategy either ignores success indicators or misses the leading indicators.
  • Bad product strategy doesn’t provide a rigorous point of view on the company-level upside.
  • Bad product strategy doesn’t map the proposed choices to cohesive actions.
  • Bad product strategy attempts to conform to executives’ pre-existing opinions about what should be done with the product.
  • Bad product strategy tries to sound visionary and ambitious, usually by employing Rah-Rah language and Apple Pie positions. Bad product strategy often reads like a prayer.
  • Bad product strategy optimizes for near-term consensus.

Why we are addicted to insight porn

  • The insight category is appealing because we put consuming content (learning) and taking action into the same box.
  • Insight porn is inherently bad when you don’t take any action from the learning.
  • The fastest way to make progress requires taking action.
  • Always reflect on the form of content you are consuming and design better growth.
  • Reframe insights into concrete actions