Comment by mprovost | Hacker News Reader

Comment by mprovost | Hacker News Reader

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!

Reply on news.ycombinator.com