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

121–130 of 162 posts

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

#121

Post by djdhrbrh »

setgree wrote: post #51
ChrisMarshallNY wrote: post #30

Earlier quoted context omitted.

> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…

> It's really hard to find fiction books, that are less than 500 pages. To play editor for a moment — your sentence needs no comma, and it’s easy to find fiction books with fewer than 500 pages ;) Was a clause omitted?

https://www.btb.termiumplus.gc.ca/tpv2guides/guides/pep/inde...

The suggestion is to never separate a subject from a verb or a verb from its object

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

#122

Post by eatonphil »

JJMcJ wrote: post #119
eatonphil wrote: post #57

Earlier quoted context omitted.

> It's really hard to find fiction books, that are less than 500 pages. Allow me to introduce you to the myriad Maigret novels by George Simenon. :) They are my favorite filler books when I want something good at only 150-200 pages.

These days shorter fiction is almost always published as part of a collection, unless you are selling on line or self publishing in print.

Is this in response to the wrong comment? I'm giving an example of the opposite of what you're saying.

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

#123

Post by ChrisMarshallNY »

JJMcJ wrote: post #120
bombcar wrote: post #97

Earlier quoted context omitted.

Apparently that was a bit of the style at the time (one of them delves into the Paris sewer system) to kind of "show off". Some other contemporary works are clearly written to be serialized.

Once downloaded a copy of Hound of the Baskervilles, broken into chapters as separate files. Each chapter was almost exactly the same length, within a few hundred characters, showing that it had been serialized first and chapters were sized for publication.

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.).

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

#124

Post by CharlesW »

sealeck wrote: post #87

- read your writing aloud (it _really_ helps to improve it) when you review it - just write and then edit - better to have written something (even if it's not great) and then make it better. Especially in writing perfect can be the enemy of good. - step away - sometimes it helps to review your writing after maybe 1 hour or a day or a few days - READ MORE - reading well written stuff really helps

> just write and then edit - better to have written something (even if it's not great) and then make it better.

Related: Do not be precious about what you've written as you rewrite. "Kill your darlings", as the saying goes.

https://www.masterclass.com/articles/what-does-it-mean-to-ki...

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

#125

Post by ChrisMarshallNY »

djdhrbrh wrote: post #121
setgree wrote: post #51

Earlier quoted context omitted.

> It's really hard to find fiction books, that are less than 500 pages. To play editor for a moment — your sentence needs no comma, and it’s easy to find fiction books with fewer than 500 pages ;) Was a clause omitted?

https://www.btb.termiumplus.gc.ca/tpv2guides/guides/pep/inde... The suggestion is to never separate a subject from a verb or a verb from its object

Hey, thanks for that! Proper comma (and semicolon) usage is always a challenge for me.

I decided to develop the habit of the "Oxford Comma," but I don't think I have it down, yet. It also seems to be "un-American." American English does not like commas.

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

#127

Post by Grimm665 »

Lot's of examples mention techniques, I'll mention tools. Find an editor you like to write in, extend it with plugins that help your flow if it's the kind of app that allows it, and learn all the in's and out's to make writing as easy as possible.

I don't have a strong background in technical writing, but often get compliments on my documentation and the secret is org-mode; it makes writing structured documents easy, and there are many tool for converting org-mode docs to any format needed, so it adapts to any audience.

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

#128

Post by rg111 »

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™.

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

#129

Post by no_identd »

gnuvince wrote: post #114
no_identd wrote: post #108

I have a whole Twitter thread on that, here: https://twitter.com/no_identd/status/1220913617408864257 Prompted by my discovery of this book: https://link.springer.com/book/10.1007/978-3-030-10756-7 "A Math-Based Writing System for Engineers: Sentence Algebra & Document Algorithms", by Brad Henderson Edit: Altmetrics just revealed to me that apparently a cheesy corporate marketing video for it exists: https://youtu.be…

Haven't read it, but my reaction to the 2 minute video is "excrement" [1]. [1] https://www.youtube.com/watch?v=LjHORRHXtyI

Well, yes, but tell that to the proof assistants, automated theorem provers, academic snowclone^W^H phrasal template banks, and highly bullet pointed lists of Corporate ISO9000 series GRC Policy & Procedure Work Instruction Drafting Style Guide Manual Template Files as well as the resulting legislative outputs( via lobbying, lol). Cf. my points in the Twitter thread, on proforms, thematic relations, and one anaphora¹.

There exist only so many ways in which to formally answer arbitrary instances of the 7 fundamental questions (yes, 7, not 5—or six, like IBM's Zachman framework would have one believe.).

¹ the Dalai Lama walks into a pizza place and asks: Can you make me one with everything?

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

#130

Post by euroderf »

Brystephor wrote: post #105
Gaessaki wrote: post #81

Lots of great advice here. One piece of advice I got from my publisher when authoring a technical book was to first break down what I was going write into headings and subheadings, and if possible, into sub-subheadings. Then review that to see if your flow is coherent and whether there are sections that are missing, or could be extracted into another text. Personally, my process after this is to express my thoughts i…

> Also, I see some comments on keeping things short and to the point I think this is true. Another way of saying it might be to write things intentionally and make sure each sentence contributes to a goal. You can have humor and personality in the paper, but make sure you don't have filler or meaningless words that you're just writing off as personality. I love when a document is easy to read and is thorough. Side ra…

An acronym glossary up front is often helpful. But the current practice seems to be to add copious whitespace until it fills two or three pages, when a fraction of that would suffice.
Post reply on HN