Do you write good? The power of the written word in software

Famously, software engineers dislike documentation. And yet, we are surrounded by examples of excellent technical writing. There are more great technical blog posts, academic papers, wiki articles, READMEs, text books (and newsletters) than we could ever possibly read...

It always depends

Kent Beck recently published The Documentation Tradeoff. There are lots of useful thoughts here, but here's one takeaway:

In the end, write the docs you want to write. If no one reads them, or if readers find they are out of date, then consider not writing them next time. But don’t let anyone shame you into wasting time. The question is not, “Do you have documentation?” but rather, “Do you communicate clearly?”

This article caused some discussion amongst the Instillers, with one regretful comment: “I don't think my documentation has any impact at all, as when someone needs something they'll ask”. Which raises the question, what if there's no-one to answer when I ask?

Is the answer always AI?

There's a sentiment amongst some in the industry that AI will mean the end of developers. We don't believe that, but that won't stop some organisations cutting staff numbers because of it. You might find yourself on a small or a new team, with limited implicit knowledge of the application you’re building. Only good documentation will save you then.

Over on the StackOverflow blog, there's a long article about the effects of AI on software teams. At the heart of Charity’s post is this:

This is an apprenticeship industry, and productivity is defined by the output and carrying capacity of each team, not each person.

Having good documentation as well as quality code raises the carrying capacity of the team.

Here's a blog post from Ian Daniel Stewart about good communication. He nicely summarises some techniques learned from a video by Vicky Zhao. There's definitely some stuff we can use in our writing, whether that's a wiki, README or Slack message. The one thing you need to know is “The easiest way to get to the point is to use the word ‘one.’”

Need some inspirational quotes to brighten up a boring email? Try this list, for example from Nicklaus Wirth:

A primary cause of complexity is that software vendors uncritically adopt almost any feature that users want.

Programming in English?

For the modern knowledge worker, writing is integral to the day job. Documentation is only the tip of the proverbial communication iceberg. Our days are filled with writing emails, sending Slack messages, creating proposals, writing blog posts... the list is endless. But writing should be seen as more than perfunctory. As David McCullough famously said:

Writing is thinking. To write well is to think clearly. That's why it's so hard.

If you are a developer and seriously don't like writing, then ask yourself, is writing any different from programming? The language we use to describe how writing and coding are structured might be different (e.g. sentences & paragraphs versus methods & classes), but is the purpose of the these structures and decompositional-thinking that goes into both not the same, more or less?

Value in complexity

If delivering customer value is the primary purpose of a software engineer, managing complexity is the most significant challenge they face as they do it.

Jim Nielsen has some thoughts on this in Overcomplicating Things Is So Easy where he sees parallels between NASA's recent moon mission and software development.

What technologies or tools make you think of that phrase — “a design so primitive, it struggles to find ways to fail”?

Speaking of primitive designs, or rather the absence of them, the 2023 State of JavaScript was released recently. Definitely worth exploring.

Between server components, server actions, signals, compilers, and more, we're seeing new innovations pop up faster than most of us can handle.

Three links about Types

• Some tips for improving the performance of TypeScript

• A discussion of a similar problem with the speed of type inference in Swift

• Gleam, newly at 1.0, is a type-safe language build on Erlang

And two for frontend

• Using attribute selectors for the class attribute in nested CSS

• A GitHub repo filled to the brim with frontend learning resources

And finally, since good writing helps us communicate, to find our voice, here’s Andrew’s recent livestream for JetBrains Academy focusing on How Educators can help Young Professionals develop an authentic voice. (By the way, the French in the preview text is the famous Blaise Pascal quote from 1657, “I have made this longer than usual because I have not had time to make it shorter.”)