Advent of Technical Writing: Style | Hacker News Reader

Advent of Technical Writing: Style

jamesg.blog

71 pointszerojames17 comments

The biggest level up an engineer can get is learning how to communicate and write well.

Many can whip up a full stack app; fewer can document what they did coherently; fewer still can communicate what they did and why to end users and customers.

There's good money to be made in being a great engineer _and_ a great communicator!

The biggest level up someone can get is learning how to communicate and write well.

Fixed that for you.

> The biggest level up someone can get is learning how to communicate and write well.

I am not sure it is so generalisable. For example, between learning how to code and learning how to communicate and write well, I do not know which would be the bigger level up.

If you can't express clearly want you want to code you are going to waste time brute forcing.

Let's consider the implications of this statement. If it were true, all capable programmers would be good communicators. Are they?

Do capable programmers by definition never brute force solutions?

I will misquote you like so:

fewer still can communicate what they did and why even to themselves.

One of the hardest things with my Rust book has been finding my own technical voice. Initially I tried a more casual/funny style, but it didn't feel authentic. Eventually I came up with a more technical style where I avoid the passive voice altogether, which can be really difficult but I think ends up with a better result. Some days it feels like my editing process is just going through a chapter rewriting any passive voice which crept in when I wrote the first draft. It feels much more exact: "The ch variable is updated to the next character in the string" vs "The for expression updates the ch variable to the next character in the string".

Congratulations on writing a book! That is a big deal.

I spend a lot of time writing blog posts, where the limited length (< 2k words) helps with sticking to a style. Longer proses are more difficult. You have more transitions to manage.

I mostly use direct language ("X is Y. This means..."). I try to be as concise as possible, but I sometimes I am more wordy than I need to be.

With that said, I pay attention to how I can be more welcoming "In this guide, we will..." (emphasis on "we"), "we are going to walk through" ("walk through" rather than "discuss", etc.), and so on.

In my personal writing, I like being more humorous where I can. I have an upcoming guide coming up on content deprecations which will start with:

    > Taylor Swift's lyric "'Cause we never go out of style" doesn't apply to documentation.

Everyone writes in their own way. This is to be embraced. There are so many words from which to choose. We can choose which ones we want!

The hardest part about technical writing IMO isn't the wording, it is the structuring. So answering the question how much time to spend on which topic, how deep to go into it, in which order to explain things etc.

Wording is not unimportant as well, but my feeling is if you nail the structure the wording will flow way more easily.

Looks like a handy resource you're building here, thanks for this.

FYI the category link right under the title links to a different category to the link below, and the first link only contains one post.

Will fix! Here is the link that should be there: https://jamesg.blog/category/advent-of-technical-writing/

Not featured in this series but a precursor and canonical read is: https://jamesg.blog/2023/11/27/technical-writing/

Technology is almost as much a communication problem as it is a technical problem.

Any guidance for anyone that wants to become a technical writer?

I wrote some reflections in https://jamesg.blog/2023/11/27/technical-writing/ that cover the "what", "why", and a little bit of the "how" of technical writing.

If you have already decided "yes, I want to become a technical writer!", write, a lot. If your job doesn't involve writing, start a blog. Write about the technical challenges that interest you; the web, databases -- anything! Having public examples to which you can point will look great to employers.

Thanks.

I'm a little puzzled at this blog post. This is not good writing.

Reply on news.ycombinator.com