Hacker News Reader

Comment by oscillonoscope | Hacker News Reader

In my experience, writing skill rarely matters as much as people think. A large portion of my coworkers won't bother to read what anyone wrote or put effort into comprehending it. I try to make good documentation but I know it's pretty much just for my future self.

View on HN

This is _exactly_ why it is important.

Most of what you write will be skimmed or not read at all. The only way to increase your odds is to make your writing engaging (to improve chances of it being read) and clear and concise (to improve chances of comprehension).

Another oft overlooked skill is to know when to repeat your message in multiple places, and how to do so without it being irritating or noisy or irrelevant (see also: when not to write anything at all). Again, this increases the chance your message gets across.

There is no amount of writing skill that allows people to read complex technical documentation without any effort put into reading comprehension. All you're going to do is put your own career on hold as people see you putting large amounts of effort into nothing productive. Dave gets his documentation done in a sprint, why can't you?

Obviously your context will vary. My experience is not your experience.

Early in my career I took something that was technically complex for me, and wrote it up as a book, using the path that lead me to understanding it.

Assuming that some of my peers might benefit from what I learned, I "self published" (aka printed copies on demand on my newly bought double-sided printer) and sold it for $50. I sold about 1000 copies over the next few years.

The money wasn't earth-shattering, but the effect on my career was immense. I was the one who literally "wrote the book". As far as resumes go, it's pretty up there.

Part of the success (I think) was that it was specifically designed to be an easy read. The goal was to get to the end and "know" a bunch of stuff, without it ever being anything but obvious.

I think it was helped by understanding where my own mental blocks were, and by unpicking those blocks, allowed others to easily disassemble and pass them.

In my experience the biggest block to learning is in understanding that something we absolutely positively know to be true, is actually false. Without letting it go first your brain refuses to accept the new (however simple) because it clashes with what is "true". But that's a digression for another thread.

Writing a 'book' early in your career definitely sounds like it could open doors but that's a clear edge case. I'm talking about internal documentation. I don't think it's reasonable to put the entire onus of communication on the writer and I've never seen a company value engineers who put large amounts of time into perfecting documentation.

It's completely alien to me that people here seem to believe engineers should be spending time making requirements and architecture documents more engaging. You're paid to read the thing, just read it.

I agree with this, immensely.

Your goal is to get your message across when your writing is skimmed.

That takes immense skill as a writer. Immense skill.

Paris Review is a great book to get an overview of mastering this skill.

Reply on news.ycombinator.com