4 ms·
Advent of Technical Writing: Style
- nunez 3y agoThe 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!
- Scarbutt 3y agoThe biggest level up someone can get is learning how to communicate and write well. Fixed that for you.
- azangru 3y ago> 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.
- Scarbutt 3y agoIf you can't express clearly want you want to code you are going to waste time brute forcing.
- sorokod 3y agoI will misquote you like so: fewer still can communicate what they did and why even to themselves.
- justinator 3y agoAny guidance for anyone that wants to become a technical writer?
- zerojames 3y agoI wrote some reflections in https://jamesg.blog/2023/11/27/technical-writing/ 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.
- justinator 3y agoThanks.
- justinator 3y agoI'm a little puzzled at this blog post. This is not good writing.
- h4l 3y agoLooks 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.
- zerojames 3y agoWill fix! Here is the link that should be there: https://jamesg.blog/category/advent-of-technical-writing/ 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/ https://jamesg.blog/2023/11/27/technical-writing/
- anikdc 3y agoTechnology is almost as much a communication problem as it is a technical problem.
- mprovost 3y agoOne 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".
- zerojames 3y agoCongratulations 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!
- atoav 3y agoThe 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.