Telepathic technical writing

My whole career, I've tried to follow the principle of "if you didn't write about it, it didn't happen". Writing happens in many forms: blog posts, Slack messages, issues, READMEs, release notes. Each requires a unique style: with blog posts you can add flourish whereas most issues should be to the point, concise yet comprehensive. Learning to master these styles will take time - and any new developer will need to take time to adapt. Likewise, each workplace or open source project has their own style of writing in different formats. Whether it's asking questions on Matrix or answering questions on a mailing list, if you treat one as the other you're going to have a bad time.

I didn't used to have a firm affinity for writing when growing up. A combination of being taught only through Welsh, and Welsh being significantly different from English, led to me having a poor grasp on the English language. I loved books though, and would read most days for at least a couple of hours. Eventually as I got into programming and the internet in general, I found others in various locales, and that helped me develop my writing abilities. Sometimes they directly pointed out my flaws, sometimes I just developed better writing habits simply through exposure to those who wrote well. It wasn't something I was naturally good at, and it's something I'm still working on.

There's a joy to writing. With every use of punctuation, you control the reader's internal monologue. With every rule they teach you in school, there's another rule that can be broken. You can have short sentences for dramatic effect. Or you can go on long rants, broken up into smaller parts through commas, so that the sense of complexity is heightened. This is different from speaking out loud: a good speaker will use different sentence structures too, but when you're listening you're usually not repeating what they said inside your head.

At work, the majority of what I do is writing. Coordinating between people, announcing things, describing issues, writing blog posts. There's not a day that goes by where I don't write something, and I suspect that's true of a lot of people. Slack messages fall into that category, too. The importance of being precise depends on which method of communication it is - if it's a back and forth between some people trying to fix a problem, then sharing what you're looking into and what you think is important. Popping in as a superhero, fixing everything, then disappearing just isn't feasible when you've got a big dependency chain. However, when writing a blog post, you're telling a story. A blog post should be engaging to the reader, to convey a message and information.

Working on open source is not that different from professional work. If you're trying to debug some issue, usually it's most effective to jump onto whatever chat platform you use and work through it with someone else. However, in open source, things are a little more async. A message you send might not get a reply til the next day if the person you're talking with is based somewhere else in the world from you. Issues might not get looked at until the maintainer is doing a sweep of issues. For that reason, I generally try to write more blog posts: blog posts are always async, but they can lead to conversations and debates, once the reader is done reading. There's also the nature of blog posts being one-to-many, whereas chat is many-to-many, if done in a public channel. One-to-many forms of communication should generally be more formal, but can spread ideas and thoughts more coherently than many-to-many. I generally have the belief that my blog posts don't need to be purely factual to be interesting, which is why Derw's changelogs are combination of thoughts, ideas, and short descriptions of merged changes.

Use of the written word is truly magic: to be able to take an idea, a concept, a thought, and transmit it out to other people is amazing. Talks can be given at a conference, but require either great on-the-spot speaking, or a lot of preparation. With writing, you can move a sentence up or down, or break it down so it flows differently. You can write a script to achieve the same with spoken word, but only through writing can you directly interface with the reader's internal monologue. Clever writing can not just communicate empathy or anger, but also lead the reader to feel the same. All from the comfort of your keyboard.

Some of my favourite writing has been when I get a chance to represent some interesting work, something cool me or my team has made. To unify the readers in understanding _why_ the work was interesting, why it was cool. A poorly written announcement will state what has been done, but not why it was done, or how it was done. The goal is to take the reader with you, as if they were there for every thought and decision that lead to your creation. Sometimes writing about what you did can be just as important as doing the thing itself

---

With that said, I figured I'd share my own personal guidelines that I try to follow. I don't think they're perfect, and as always with these kinds of guidelines - you must adapt to your audience.

Some terms

Some terms before we get into that though, just to make reading easier:

• Message - what you get when you hit "enter" on Slack

• Story - the content of what you're trying to convey. Might be a blog post, might be a collection of messages on Slack

• Thread - a grouped discussion that begins underneath a single message on Slack, or a chain of messages between multiple people in email

General rules

Jokes are okay if you think the readers will get it - and that they won't be offended by it. Different circles find different things funny, and different things offensive. Tune yourself to your audience. Unless it's relevant to the story, collapse all attachments as large attachments block the flow of the story. Don't ping people unless you need to - giving credit is okay, if it's an urgent message that's okay. If it's just an update that people can read in their own time, never ping. Definitely avoid @channel at all costs. Default to the most public forum that a message can or should be given in. Avoid private messages when a channel would equally work.

Slack - to a person on familiar terms

If the message to a single person who you have a friendly relationship with, a story can be across multiple message. You can avoid perfect spelling or grammar, though your message should still be understandable. It's more like capitalizing all yours "i"s matter less rather than posting a message that looks like you were drunk is okay. If the story is lighthearted, feel free to use emojis. Avoid bombarding them with stories outside of work hours / when they're asleep - if you really need to send a story, and you can't queue it up, prefer a singular long message rather than multiple. Avoid threads at all costs, as messages tend to get buried and lost that way.

Slack - to a group of people, formally

Use a single message when possible. Avoid too many jokes, signing off with a joke is okay, but don't make every sentence a joke. Avoid emojis as they can sometimes make your story read as if you're insincere or passive aggressive. Use a spellchecker and structure your message into multiple paragraphs. The smaller the better. When posting an image, give context. Why are they looking at this graph? Tell them. Sign off with your name and role if relevant, and let people know they can reach out to you.

Emails

The first email in a thread should be a little more formal than most. Say hi, the reason why you're emailing, the content, and sign off with your name / role if relevant. After that, there's no need for hi/bye, just get the story across. If a thread becomes long and confusing with multiple side notes or side conversations, switch to Slack or something similar. It's easy to get lost in an email thread. Email subjects should be clear and concise, but not conciseness in favour of memorability.

Blog posts

Start with a paragraph which explains what the reader is about to commit to reading. It doesn't always need to be a formal explanation - but your first sentence should set the context. Don't write more than that's necessary, but you can explore a theme within your post. Telling small related stories within the post is good, but avoid rambling or telling completely unrelated stories. Remember that when a reader reads a blog post, they might have 0 context on any of your other posts, who you are, or what your blog is generally about. If your post gets popular, it'll likely be shared on news aggregators where all people see is the title - so a good title is important.

---

I hope you found this useful, or engaging. If you want to read more of my favourite writing, check out my post on my love for programming languages, or my passion for programming. If you want to know more about Derw, check out the homepage. To stay up to date, follow me on Twitter or subscribe. I try to do one Derw-focused post and one general programming post once a month each.