Ask HN: How to level up your technical writing? • Hacker News Board

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

#111

Post by gautamdivgi » Sat, Jun 25, 2022, 6:03 PM UTC

For more of a process on how to get docs cycle through a dev review - The oxide computer RFD process - https://oxide.computer/blog/rfd-1-requests-for-discussion. I tried to use something similar for my team but got a lot of eye rolls that docs would need source control. We use a wiki but it's messy and not a lot of review control. Writing the doc is one thing. Making sure it's effectively communicated, reviewed, versioned and published should also be a part of the documentation process.

One pesky little detail is that documents take a lot of thought to write and this translates into a good bit of time to get a document out for review. If you have a "how fast are you closing your JIRA tickets" manager, it can be hard to justify and will come back to bite you (unfairly so, but such is the life of a sw. engineer).

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

#112

Post by fnord123 » Sat, Jun 25, 2022, 6:08 PM UTC

ghaff wrote: post #49

fnord123 wrote: post #23

Strunk and White. To some it will be too obvious. But English speakers (especially English as a second language people) outside the US have often never heard of it.

Unfortunately, this is now apparently behind a sign-up wall but for a counterpoint: https://www.chronicle.com/article/50-years-of-stupid-grammar... "The Elements of Style does not deserve the enormous esteem in which it is held by American college graduates. Its advice ranges from limp platitudes to inconsistent nonsense. Its enormous influence has not improved American students’ grasp of English grammar; it has sign…

The article is needlessly contrarian and negative. The book is useful to get students or anyone playing a trade writing from 3/10 to a 7/10. A lot of critics lose sight of this.

It's a great book to use for guidelines to start with when building out your own style. If youre an editor and want to use it to compell others to write with a style, it's less useful.

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

#113

Post by JJMcJ » Sat, Jun 25, 2022, 6:13 PM UTC

ChrisMarshallNY wrote: post #30

marcpaq wrote: post #24

Tech writer here. The absolute, invariable first rule in tech writing is to know your audience. Understand not just their technical problems but take the time to empathize with why they have these problems in the first place. Tech writing isn't about documenting, it's about finding the best way to explain something to people so they can solve their problems. Oh, and use an editor (the human kind, not the digital kind…

> 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…

If you follow the publication of big name writers, there is a tendency for their later works to get longer and longer, and, as you say, harder to read.

Examples include Robert Heinlein in Science Fiction, James Michener in general fiction, Herman Wouk in general fiction. For Wouk, his well known Caine Mutiny is a fairly long book, but it's tightly written. Later works not so much.

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

#114

Post by gnuvince » Sat, Jun 25, 2022, 6:16 PM UTC

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

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

#115

Post by JJMcJ » Sat, Jun 25, 2022, 6:22 PM UTC

YeGoblynQueenne wrote: post #54

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. 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 copy of each of your books.

If you are big time popular, they might order 20 copies, like the last few Sue Grafton books.

Similar for ebook and audio books.

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

#116

Post by maxekman » Sat, Jun 25, 2022, 6:23 PM UTC

ayewo wrote: post #109

Lots of solid advice already. If you are up for it, you could try moonlighting as a writer for technical content marketing agencies. You get paid on the side, while also subjecting your writing to editorial criticism until it is ready for publication. https://draft.dev/write https://contentlab.io/writeforus/

Cool tip! However I don’t think I would have the motivation to do a good job in that (and sadly no time for it).

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

#117

Post by maxekman » Sat, Jun 25, 2022, 6:26 PM UTC

SKILNER wrote: post #103

Someone else mentioned Strunk and White's Elements of Style, but in the true spirit of that book let me just cut to the chase and say, "omit needless words." Our brains only have so much space in them so you only get to cram a small number of words into someone else's brain; make them the most productive words possible. When writing, it's harder to remove words than write them.

A bit like code then, optimize for easy reading rather smarts when writing it.

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

#118

Post by ayewo » Sat, Jun 25, 2022, 6:28 PM UTC

maxekman wrote: post #116

ayewo wrote: post #109

Lots of solid advice already. If you are up for it, you could try moonlighting as a writer for technical content marketing agencies. You get paid on the side, while also subjecting your writing to editorial criticism until it is ready for publication. https://draft.dev/write https://contentlab.io/writeforus/

Cool tip! However I don’t think I would have the motivation to do a good job in that (and sadly no time for it).

No worries! Just threw it out there in case it might fit in with your goals.

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

#119

Post by JJMcJ » Sat, Jun 25, 2022, 6:34 PM UTC

eatonphil wrote: post #57

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

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

#120

Post by JJMcJ » Sat, Jun 25, 2022, 6:36 PM UTC

bombcar wrote: post #97

klodolph wrote: post #32

Earlier quoted context omitted.

I always like to point at Victor Hugo. In Les Misérables, apparently (I didn't count), more than a quarter of the text is essays which do not move the plot forward. The essay about Waterloo is the most egregious example.

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.