Hacker News Reader

Comment by korroziya | Hacker News Reader

I agree with most of the points but I will say (as someone who writes for a living) that it is "easy" once you've learned how to do it. Writing is hard as hell if you don't know the rules past high-school level requirements.

Case-in-point: several of my non-work friends are ESL and some of them are taking technical writing courses. I've seen their assignments and have given them copyediting help. They're shocked that I can carve out the assignment in five minutes. Usually their problem is the first rule from Strunk and White: use less words.

View on HN

*fewer words, mr. professional writer

jk ... but only sort of

I hope it's a joke. That foolish school child rule should never be mentioned by adults. Unless you think "<" is the "fewer than" symbol...

FWIW, "fewer" is correct because "words" is a countable item. Also, Strunk's advice was, "Omit needless words".

Paraphrasing is hardly a literary crime but yes.

For sure, the only issue is that it completely changes the meaning.

I consider myself pretty decent at writing. I don't love writing but it has always come fairly naturally to me, much easier than it appears to come to most people. Which is surprising, given how absolutely mediocre I am at nearly everything else in life. :) ("Those that can, do. Those that can't... write?")

I'm frequently aghast at how utterly _terrible_ most technical documentation is. Even the docs for a lot of prominent enterprise and open source software is just awful to use. What drives me the most insane is dry, passive voice. Passages that descriptive rather than prescriptive ("the widget is a surmounted on a logarithmic casing, widdershins of the two spurving gears"), contain zero diagrams or illustrations of how things are put together, and _definitely_ don't contain anything like a tutorial or getting-started guide.

Every once in a while I consider jumping into the field of technical writing just to clean it up a little. But I would probably find it immensely dull after a short period of time.

I have explored technical writing a little bit. There are actually a fair amount of people that have majored in the humanities or literature of some sort. They complain about how they have to write in a dry, passive voice. If some of them had their way, the documentation would read differently.

I don't think anyone in tech writing is trying to put out bad documentation. I've read many complaints about not being given access to the device or software, being left out of license provisioning, being kept out of the loop in sprint planning and other meetings, or being told late in the documentation stage that functionality has changed. If the writers don't have access to blueprints or can't access the software, documentation doesn't get pictures. Some of the devs and engineers respond poorly to requests for screen grabs or doing other administrative work for the tech writers.

I don't think there is a simple solution here. What are the incentives and how does tech writing help or harm. In some cases, helping a tech writer is time spent away from development. Or you can blame UX issues on poor documentation to blame the tech writers.

Yeah. These days I mostly do a lot of writing and a lot of editing. And I suspect I can sometimes coast a little bit because people assume that what I do (for me) is a lot harder than it actually is. Though it's never really easy and does involve a lot of pacing to get through some writing "problem."

Reply on news.ycombinator.com