Never one to miss a chance to write and share something, here’s my response to this :) (View Highlight)
Firstly, I like to share information. That could be a new tool or technique that I’ve learnt, a clever trick I’ve discovered, or sometimes away from the technical and into the realms of life pondering and navel gazing. In the case of this very blog, it’s to share my thoughts on something that interests me. I could have written some notes and sent them directly back to the person who asked the original question, but if it was useful to them it’s hopefully useful to others—so therefore it’s worth writing up and publishing. (View Highlight)
The second reason that I’ll write is to learn about something. It’s one thing to hand-wave one’s way through a presentation. It’s another to commit pen to paper (well, bytes to disk) and explain something. Quite often I’ll realise that there’s a gap—or gaps—in my knowledge that I need to explore first before I can properly write about something, and that’s the very reason that I do it. (View Highlight)
There are several pleasant side-effects from writing too. Anything in the public domain (such as your blog, but also open-source project documentation, etc) helps establish your credibility in an area and awareness by others of you. We may never reach the stratospheric heights of someone such as Kelsey Hightower, who has wowed a generation of developers with their Tetris-playing skills, but being known as that guy who wrote a really useful blog that helped others is still a really nice feeling :) (View Highlight)
When I write I try to write for myself—a developer, interested in a thing. That could be a new technology, an in-depth explanation, a random musing on life, or anything else. Would I like to read the thing I’ve read? Does it avoid the pitfalls that plague the soulless bland crap that some companies churn out, stick an emoji on, and call developer marketing? (View Highlight)
There are three key dimensions that it’s useful to consider here:
• clarity
• personality (also called voice)
• uniformity of content. (View Highlight)
You can roughly overlay these dimensions across the range of written materials that we might write:
(View Highlight)
Things aren’t always so simple, and for some platforms in particular there’s quite a range:
(View Highlight)
The first of these dimensions is pretty straightforward and shouldn’t really vary. Whatever you write, for whomever you write it, it has to be clear. Writing clearly means everything from sentence construction and paragraph breaks through to the structure of your article. It can be surprisingly hard to do but is crucial if you want to write material that people will want to read. (View Highlight)
One neat trick when it comes to clarity is to remember that what you leave out is as important as what you leave in. This is going to be very context-specific. Documentation, by definition, should be comprehensive. A blog, on the other hand, might want to get to the point sooner and just provide a link to background material for the reader should they want it. Less is often more, as they say. (View Highlight)
Some types of writing are going to have greater scope for individuality than others, but all have the potential to at least be accessible and clear. For example, just because you’re writing documentation doesn’t give you a pass to copy and paste the requirements doc in all its generic and obscure complexity. Write documentation that you as a developer would like to read. It can be complex and precise, yet still accessible. (View Highlight)
Personality and Voice
Should the ‘voice’ of the author be allowed to come through in the writing?
This is very much a sliding scale. I’ve jotted down some of the characteristics you might associate with either extreme of the scale. This is not to say that by definition you’d put cuss words into a blog so as to convey your voice—but as an example of something that you might see at that end of the spectrum and definitely not at the other.
(View Highlight)
You’ll generally find that generally writing mediums such as a project report to stakeholders or product documentation requires a neutral voice. That’s not to say boring, but it is to say that a certain uniformity is required. In the case of a project report, the message mustn’t be obscured by colloquialisms and the such. And can you imagine the cognitive dissonance if a set of documentation were written by multiple writers each looking to stamp their personality on the pages? (View Highlight)
When we get to things like blogs and other types of writing we deliberately want to include some personality. How much is up to you to calibrate with your audience and yourself. There is a “Goldilocks” zone here—enough personality and genuine voice coming through to convince the reader that they are reading something that was written by someone who is actually interested and informed on the matter, but not so much that it gets in the way of the content. (View Highlight)
Uniformity and Standardisation
This has a strong relationship with personality and voice but relates a lot more to the structure and content of the material
Using the example of blogs, you’ll find that blogs for a company or project are going to have a strong focus on the consistency of messaging and structure. There’ll be an introduction, there’ll be context; it’ll be comprehensive. (View Highlight)
A Holistic View
It may seem like there’s going to be a linear relationship between the two dimensions. As we decrease the amount of personality coming through in an author’s writings, we’re also going to move towards a much more standardised set of writing.
I’d suggest that it’s not always the case. (View Highlight)
A startup may value personality much more over standardisation, perhaps only really dropping the voice when it comes to something like documentation (and even then, perhaps not entirely).
(View Highlight)
At the other end of the scale, some companies—usually large corporations—have the habit of squeezing the last inch of life out of any kind of writing, making the relationship a much different one. (View Highlight)
Here there’s little voice even where you might hope to find it, and that rapidly drops off into nothing very soon after:
(View Highlight)
The wildcard within this is the social media teams of large companies who are given the remit to be Funny and Engaging, but this is usually outside the scope of developer writing and more into the field of condiments and fast food chains (View Highlight)
Like a favourite pair of jeans that’s well-worn, comfy, and slightly saggy round the arse, I have a go-to structure for writing. Come to think of it, I use it for lots of conference talks too. It looks like this:
An intro
What is this thing, and why should the reader give af be interested?
This could be a brief explanation of why I am interested in it, or why you would want to read my take on it. The key thing is you’re relating to your audience here. Not everyone wants to read everything you write, and that’s ok.
Let people self-select out (or in, hopefully) at this stage, but make it nice and easy. For example, if you’re writing about data engineering, make it clear to the appdev crowd that they should move on as there’s nothing to see here (or stick around and learn something new, but as a visitor, not the target audience). (View Highlight)
A recap
Make sure you don’t just finish your article with a figurative mic drop—tie up it nicely with a bow (a 🙇🏻 or a 🎀, either works).
This is where marketing would like to introduce you to the acronym CTA (Call To Action) 😉. As an author you can decide how or if to weave that into your narrative.
Either way, you’re going to summarise what you just did and give people something to do with it next. Are there code samples they can go and run or inspect? A new service to sign up for? A video to watch? Or just a general life reflection upon which to ponder. (View Highlight)
At the risk of repeating the owl meme I would give the following advice: just start writing!
I don’t mean just go write an article. I mean start writing something, anything.
Some notes, some snippets, some whole paragraphs. It might even look like this
(View Highlight)
The point is you now have something. The sections and threads of a story start to fall out as you write more. What starts as one section perhaps becomes two as you realise there are individual elements to tease out. (View Highlight)
That random link you made a note of, where does it fit in what you want to say? Is it pushing the need for a new section or tangent, or is it actually not so relevant and you can park it? Not sure? Well just leave it there and think about it again on the next pass round. (View Highlight)
I’ve recently found that using a Pomodoro timer is an effective way of getting me to focus, and to take a break. Instead of staring at a screen, descending into a pit of despair at the stagnation of an article, you spend a chunk of time and then step away. Perhaps you come back to it after the break or maybe wait longer. Like many problems in life, things resolve themselves given time to marinade in the recesses of one’s brain. That paragraph that just wouldn’t write itself will come spilling out of your eager fingers onto the keyboard. The section you thought you’d nailed—turns out you didn’t and it needs a rewrite. But all these things come with time and iteration through the text. (View Highlight)
Find a really good reviewer and copyeditor
You might think you’re good at writing. You’re probably not that good at writing that the eye of an excellent copyeditor won’t improve it, nor the tactful input of a good reviewer enhance it.
Good copyeditors will respect the voice that’s present in your writing and work to preserve it whilst improving the clarity and grammatical accuracy of what you’ve written.
Good reviewers will grok what you’re saying and help distil and mould it into a better shape. (View Highlight)
What to write will often come from the “Why” above, but let’s imagine that the creative juices aren’t flowing and you still really want to get a blog written.
A really excellent place for ideas is the community around the thing you want to write about. Go and lurk (or even better, join in) at StackOverflow, Twitter, Slack, Discord…wherever the community is:
• What questions do people repeatedly ask?
• What are the anti-patterns and misunderstandings that you see?
• What are the new trends?
• What cool things can you do with $THING
In short, if it would be interesting to me then I would write about it. (View Highlight)
Make sure to also watch this lecture in which the concept of value and ideas is discussed. tl;dr if you aren’t writing about something interesting to the reader, it has no value, regardless of its value to you. (View Highlight)
This is a very personal preference. I’m not keen at all on growth-driven blogging styles. You know the sort: listicles, SEO bait, etc. It’s low-grade, developers see through it, and it tarnishes the blogger’s image IMHO. That said, if you write a good blog, there’s no reason not to structure it such (“Top Five Tips for Successful Developer Writing”) but put the horse before the cart, not the other way around. (View Highlight)
To summarise this whole article, bear in mind that these two statements are not mutually exclusive:
Write for yourself. Work out what you would like to read, and write it.
Think of the reader and what value you’re providing to them in your writing. (View Highlight)
(View Highlight)
(View Highlight)
(View Highlight)
Using the example of blogs, you’ll find that blogs for a company or project are going to have a strong focus on the consistency of messaging and structure. There’ll be an introduction, there’ll be context; it’ll be comprehensive. (View Highlight)
(View Highlight)
(View Highlight)
At the risk of repeating the owl meme I would give the following advice: just start writing!
I don’t mean just go write an article. I mean start writing something, anything.
Some notes, some snippets, some whole paragraphs. It might even look like this
(View Highlight)