
On Technical Writing - ming13
https://arturdryomov.dev/posts/on-technical-writing/
======
voidhorse
This article, like many on “technical writing” conflates techincal writing and
_writing about technology_. In my estimation, they’re two different things.

Technical Writing is a profession with a massive set of practices, relatively
well-prescribed goals, and a long history. It’s a discipline that has almost
nothing to do with Stephen King and Strunk and White—though of course these
sources might be applied. Chances are, if you were to ask an professional
technical writer about resources for technical writing, they’d point you to a
few text books on technical communication or papers or blog posts from people
in the industry. Technical writing also has serious consequences. If a manual
for a missile has mistakes, it could cost thousands of dollars or thousands of
lives. Stephen King’s advice isn’t quite as helpful in such perilous
situations.

 _Writing about technology_ , I think, is closer to what the author is
actually pursuing here—and most tech blogs better fit this classification than
technical writing. Writing about technology is more free form, more whimsical,
full of opinion, intimations of possible approaches or solutions but not
hardened proceedural documentation.

It might seem a bit pedantic to make such a distinction, but I would really
love it if more people honored it. For instance, this article was a bit of
false advertising, since I thought it’d be about technical writing in the
professional sense (i.e. writing documentation) and not about writing about
technology in a more casual, opinionated way. It’s similar to the distinction
between programming and software engineering—they’re quite distinct pusuits,
even though the tools and techniques considered overlap.

~~~
kaycebasques
My guiding goal as a practicing technical writer is _how do I transfer
knowledge as efficiently as possible?_ For that reason I think it’s a skill
that is applicable to anyone whose job depends upon a lot of collaboration,
which is why I think we see the topic come up somewhat frequently here on HN.

I 100% agree that _technical writing_ is a discipline with a specific meaning
and is not the same thing as _writing about technology_.

------
baby
This article is actually quite empty, it starts like it is going to be about
how to write good technical content, then becomes an auto-biography, then
becomes an article on how one can get started blogging, then just end abruptly
with some statistics that probably nobody cares.

So if you came here to know how to write, Stephen King wrote a book "On
Writing" that is quite interesting and mostly reads like a novel. See it as a
"I'll read this and I'll get motivated to write".

If you came here to understand how to get into blogging: just start. Create a
wordpress, and just start writing. Focus on content, not on form. After a
while, you can think about a domain name, about a custom theme, or about
hosting this yourself on github with hugo. But don't start with the technical
parts of managing a blog, just write.

If you came here to understand how you can become a good technical writer:
keep writing. Consistence over years of writing is what makes you a good
writer. The ultimate technique for me is to give an interactive talk to people
about your ideas, and see where your audience get stuck, where they ask
questions, how different ways of explaining something get the point across.

Malcolm Gladwell does more than this: he explains an idea multiple times in
different ways. If you have the page count to do this, do it. Different people
need different ways of explaining.

(shameless plug: I'm writing a book on crypto
[https://www.manning.com/books/real-world-
cryptography?a_aid=...](https://www.manning.com/books/real-world-
cryptography?a_aid=Realworldcrypto&a_bid=ad500e09))

~~~
dnh44
William Zinsser’s “On Writing Well” is also quite illuminating in regards to
writing non-fiction.

[https://www.harpercollins.com/9780060891541/on-writing-
well/](https://www.harpercollins.com/9780060891541/on-writing-well/)

~~~
criddell
Have you read Steven Pinker's _Sense of Style_?

[https://stevenpinker.com/publications/sense-style-
thinking-p...](https://stevenpinker.com/publications/sense-style-thinking-
persons-guide-writing-21st-century)

I was thinking about reading it but it's hard to find reviews of the book that
don't include praise or criticism of Pinker's other work or the author
himself.

~~~
x1798DE
I've read it and I found it to be the most useful book on writing I've read so
far, because he grounds his advice in clear linguistic principles and he is
mostly not prescriptivist in his advice.

His advice about keeping an easy-to-understand sentence tree alone is worth
the price of admission.

------
herodotus
I am surprised that someone who claims to have been an avid reader writes so
poorly. Consider, for example,

"Fast-forward to the last year of school. I’ve started writing. It was nothing
special really, short fictional stories there and there."

The author's tense is muddled, and I have no idea what "there and there"
means. Better would be

"Fast-forward to my last year of school. I started writing. It was nothing
special really, just some short stories."

There were a few instances where the author should have used "I" rather than
"I've". In fact, I would encourage this author to avoid such contractions
altogether.

The goal of writing at least one article a month is laudable, but this author
should work on writing craft fundamentals. Perhaps a book like The Elements of
Style would help. Even better would be a tutor or coach.

------
kristianc
> There were no recommendation engines of course so I went through everything,
> itching to consume experiences left behind by humanity. Sounds like an
> addiction, right? Well, it kinda was.

Well, there kind of were. I doubt you would end up reading The Hobbit, The
Three Musketeers and Sherlock Holmes purely by accident. The idea that the
best content bubbling to the top of the popular consciousness is merely a
product of modern ML recommendation engines is for the birds.

~~~
soonerroadie
Of course there were recommendation engines - they were called librarians.

------
JeanMarcS
« Kids certainly don’t give a damn about them either. »

Well I guess it depends on how you educate them.

While I’m here eating my (late) breakfast, both are in their room reading.

They are 9yo (10 next spring). My son is finishing season 2 of Erin Hunter’s
warriors (he loves cat) and my daughter finally catch up on Harry Potter and
is reading no2 (they are not allowed to see the movies until they read the
book)

~~~
aspaceman
"Kids these days" never really goes away huh? Funny how smart phones and
social media will be our version of that.

~~~
coldtea
> _" Kids these days" never really goes away huh?_

And it's seldom wrong either.

Kids do have different behavior in different ages. Whether that's good or bad
is another thing (in some things it's bad, in others are good). But culture,
habits, etc, are not the same blob of sameness for centuries. Kids in 1950 are
different than kids in 2020 or kids in 1900.

In this particular case, indeed, kids these days seldom read books, whether in
print or eBook form.

Whether they still read social media pages, and online news, is beside the
point when it comes to reading books.

~~~
aspaceman
It’s frustrating because it’s based on anecdotal evidence and preconceptions.
It also defaults to the assumption that all change is bad.

I know plenty of kids these days who read books, lots of them in fact. Often
reading fiction and literature especially.

~~~
coldtea
> _I know plenty of kids these days who read books, lots of them in fact.
> Often reading fiction and literature especially._

Well, since you've mentioned anecdotal evidence, all the statistics say kids
read less than ever. Down to 1/4 or so of what kids in the 70s read (including
eBooks).

[https://www.humanitiesindicators.org/content/indicatordoc.as...](https://www.humanitiesindicators.org/content/indicatordoc.aspx?i=11098)

------
phlakaton
> Btw, conferences and events are dead.

The author lost me right there.

