Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How to level up your technical writing?

news.ycombinator.com

Post reply on HN
Print view View original

151–160 of 162 posts

Re: Ask HN: How to level up your technical writing?

#151

Post by warrenm »

MrPowers wrote: post #43

Blogging & measuring average time on page is a great way to see if you're able to write content that's relevant and engaging for readers. Average time on page should be at least 5 minutes for a blog post. Improving open source project READMEs and documentation is another great way to practice writing. I am writing an O'Reilly book now and having a professional editor will help you learn the common errors you're makin…

> Average time on page should be at least 5 minutes for a blog post

How do you come up with "at least 5 minutes for a blog post"

A blog post should be as long as it needs to be - and no longer

Re: Ask HN: How to level up your technical writing?

#152

Post by yrui »

I'm from a hybrid humanities and technical background. Good writing is good writing: clear, simple, and easy to read.

Books that influenced me:

Style, by F.L. Lucas

Simple and Direct, by Jacques Barzun

For technical writing, I recommend four additional disciplines:

1.) Keep the documentation up to date.

2.) Allow and encourage your readers to give you feedback about what's unclear. Then make revisions based on this. Also, re-read what you wrote periodically, and make revisions whereever you think you can improve clarity and usefulness.

3.) Provide copious examples where you show how to accomplish useful things.

4.) Use the tool you're documenting. Find errors, corner cases, and things to be aware of and document them as comprehensively as possible.

Re: Ask HN: How to level up your technical writing?

#153

Post by coxley »

Two recommendations:

* On Writing Well

* Google's free, self-guided technical writing courses

Using these, you should get much better at refining your writing. Write naturally, then go back and edit when rereading according to the your new skills.

Another thing to get better at is layering your message. Assume that some percentage of people drop off each paragraph. Important details for the entire audience should be front and center. Then gradually get more specific.

Boz has a nice write up on this: https://boz.com/articles/communication-is-the-job

Re: Ask HN: How to level up your technical writing?

#154

Post by yokuze »

yrui wrote: post #152

I'm from a hybrid humanities and technical background. Good writing is good writing: clear, simple, and easy to read. Books that influenced me: Style, by F.L. Lucas Simple and Direct, by Jacques Barzun For technical writing, I recommend four additional disciplines: 1.) Keep the documentation up to date. 2.) Allow and encourage your readers to give you feedback about what's unclear. Then make revisions based on this.…

I second the "Simple and Direct" recommendation. I stumbled upon it in a book store over a decade ago and I've never seen anyone recommend it before. Years after reading it, I still hear the author's recommendations in my head when writing.

Re: Ask HN: How to level up your technical writing?

#155

Post by larsrc »

maxekman wrote: post #75
larsrc wrote: post #70

Lots of good advice already (except there are better sources for writing style advice than Strunk & White). Here's one I and my linguist wife like: Write on paper first. Paper is more immediate and has fewer distractions, fewer ways to go back and edit at once, and leaves a bit more time to think. It doesn't require looking at a screen, which you probably do enough of already. Sure, typing it up is an extra step, but…

Very true that we sit by our screens way too much. Any reasonable work away from it is probably for the best. On this note I would like to share a really good tip (but slightly out of topic) that I got in the comments on some HN post some time ago; don’t use your phone or Internet until late morning, or at least after having really dug in to work for the day. This really helps to focus on the work at hand and avoid d…

Getting into "work mode" really helps. I did a similar thing during my Ph.D. studies - no reading email or news or gaming until lunch time, only work. After lunch, all options were open, but I then had work so swapped in that I kept on working.

Re: Ask HN: How to level up your technical writing?

#156

Post by drakonka »

JJMcJ wrote: post #115
YeGoblynQueenne wrote: post #54

Earlier quoted context omitted.

> It's really hard to find fiction books, that are less than 500 pages. For SF & F this seems to be a deliberate choice, from what I understand. This is from an iterview with Ted Chiang: TC: I think the reaction varies, because science fiction is a more commercial genre. There are a lot more people in science fiction whose goal is to make a living from writing fiction by publishing one or more novels a year. And peop…

> extreme padding First drafts tend to be verbose. Poor editing contributes to that kind of prose slipping through into publication. As to huge page counts, mysteries are similar to science fiction as genres but I don't see a push to expand to huge sizes. All genres are places where earning a living is possible. Someone said if you have a popular mystery series, every public library will buy at least one hardback cop…

I think page padding is more a thing in self publishing. I'm part of a few fiction writer communities and longer (in general) makes more money. You are advised to start with short stories and graduate to novels as soon as possible. This is especially true for authors enrolling their books in Kindle Unlimited. They are paid per page read. The more pages they can have the reader go through without boring them enough to just quit, the more they get paid.

Re: Ask HN: How to level up your technical writing?

#157

Post by harley_joe »

tetha wrote: post #36

It's not strictly from the technical writing corner, but I've learned a lot from the book "The Craft of Scientific Writing" by Micheal Allay. It's more geared towards scientific papers, but I've found the style papers are structured to be a very useful starting point for design documents and runbooks. I tend to start with something like that, and adjust it according to the audience.

The book is available for download - http://quantum.phys.unm.edu/400-18/AlleyTheCraft.pdf

Re: Ask HN: How to level up your technical writing?

#158

Post by JJMcJ »

eatonphil wrote: post #136
JJMcJ wrote: post #135

Earlier quoted context omitted.

What I meant was that books like the Maigret novels probably wouldn't be published as free standing books, but packed into collections, say three or four of them together, to get closer to the magic 500 pages. I will mention that I highly recommend Simenon's writing, Maigret series and others. He's a fine writer. The TV series with Michael Jambon is excellent. The Maigret stories are the right length to turn into an…

You can literally buy these as paperback though, directly from the publisher: https://www.penguinrandomhouse.com/series/IMA/inspector-maig... .

Of course, but remember that they were first published in 1931. The last ones were 1973 but by then they were so popular they could go against the already established trend of longer books.

Someone writing new mysteries today probably could not get a single book that short accepted by a publisher.

Re: Ask HN: How to level up your technical writing?

#159

Post by raybb »

rg111 wrote: post #128
gnat wrote: post #16

Two things I recommend: the Google tech writing courses: https://developers.google.com/tech-writing And "Bugs in Writing", which I've been pressing into people's hands for twenty years now. https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/...

15 hours ago, this book was 15 bucks, and now that I went back to the page, the book is 39 bucks with "Only 1 left in stock" message. Products on Amazon even get the Hug of Death™.

You can also read it on Open Library for free :) https://openlibrary.org/works/OL2743029W/BUGS_in_writing?edi...

Re: Ask HN: How to level up your technical writing?

#160

Post by JJMcJ »

warrenm wrote: post #147
ChrisMarshallNY wrote: post #123

Earlier quoted context omitted.

I'm trying to remember if it was Dumas, but some French author was reputedly paid by the word, so all their dialogue is incredibly drawn out ("I have a question." "What is the question?" "It is, as you might expect from me, a simple question." "By all means, please, present me with the question, that I may resolve your puzzlement." ... etc.).

That's one of the ongoing theories as to why Moby Dick was so long ... not merely to accentuate the 99.99% bordedom of whaling (with the 0.01% of "excitement"), but because he'd get paid better if it were longer Having read the "Great Illustrated Classics" edition of Moby Dick as a kid, and watched the Gregory Peck film, I can confidently assert I NEVER want to read the whole thing. Even those "condensed" versions ha…

When I read Moby Dick I found it a quick read for the length. Full of incidents and plot.
Post reply on HN