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:
A primary cause of complexity is that software vendors uncritically adopt almost any feature that users want.
Nicklaus Wirth
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 Type
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 Blaise Pascal from 1657, “I have made this longer than usual because I have not had time to make it shorter.”)
Until next time,
