[HN Gopher] Advent of Technical Writing: Style
___________________________________________________________________
Advent of Technical Writing: Style
Author : zerojames
Score : 57 points
Date : 2023-12-09 12:32 UTC (10 hours ago)
(HTM) web link (jamesg.blog)
(TXT) w3m dump (jamesg.blog)
| nunez wrote:
| 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!
| Scarbutt wrote:
| _The biggest level up someone can get is learning how to
| communicate and write well._
|
| Fixed that for you.
| azangru wrote:
| > 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 wrote:
| If you can't express clearly want you want to code you are
| going to waste time brute forcing.
| azangru wrote:
| Let's consider the implications of this statement. If it
| were true, all capable programmers would be good
| communicators. Are they?
| j4yav wrote:
| Do capable programmers by definition never brute force
| solutions?
| sorokod wrote:
| I will misquote you like so:
|
| fewer still can communicate what they did and why even to
| themselves.
| justinator wrote:
| Any guidance for anyone that wants to become a technical writer?
| zerojames wrote:
| 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.
| justinator wrote:
| Thanks.
| h4l wrote:
| 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.
| zerojames wrote:
| 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/
| anikdc wrote:
| Technology is almost as much a communication problem as it is a
| technical problem.
| mprovost wrote:
| 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".
| zerojames wrote:
| 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!
| atoav wrote:
| 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.
___________________________________________________________________
(page generated 2023-12-09 23:02 UTC)