14 ms·
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
by marcpaq 4y ago
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.)
- ChrisMarshallNY 4y ago> 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 just starting out, he was forced into being edited. I remember reading 'Salem's Lot, back in the 1970s. It was an awesome book (Relatively short, succinct, scary as hell), and made me suddenly become a Stephen King fan. As he got more and more famous, he started being able to bully his editors, to the point where his work is barely edited at all. And it shows. I really can't read him, anymore.
- klodolph 4y agoI 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.
- solardev 4y agoToo bad that wasn't in the musical. Can you imagine Russell Crowe belting an essay on Waterloo?
- warrenm 4y agoI would pay good money to watch that!
- bombcar 4y agoApparently 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.
- JJMcJ 4y agoOnce 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.
- ChrisMarshallNY 4y agoI'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.).
- JJMcJ 4y agoMany modern novels seem that way too. Not the elaborate dialog, but endless rambling descriptions. Historical novels are often big offenders. Like the author has done a ton of research, not a bad thing, but can't bear to leave any of it out, and there is no editor to say that's too much, people don't need to know how big the potato patch at the Palace of Versailles was.
- warrenm 4y agowhile not a big Western fan, I do find Louis L'Amour's compact descriptive format to be intensely engaging
- warrenm 4y agoThat'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 had enormous swaths of nothing in them!
- nonrandomstring 4y ago> Apparently, he hates being edited (most writers don't like it). I've grown to love it. It was a long road. Once you start disciplined writing an editor becomes like a personal trainer who helps you be your best. Until I learned to write with more steel and less fire, ego ruled my writing. The familiar sins are; - loving the sound of your own (inner) voice - showing off what you know rather than considering what the reader might care to hear (and muddying waters so as to appear deep) - pretentious talk (circumlocutory linguistic gymnastics) A good editor gets to know your weaknesses and corrects them gently.
- deleted 4y ago[deleted]
- warrenm 4y ago>A good editor gets to know your weaknesses and corrects them gently. Or maybe not-so-"gently" .. I'll take useful constructive criticism (regardless of harshness) over unactionable "reword" every dang day of the week (and 3 times on Sunday)
- setgree 4y ago> 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?
- ChrisMarshallNY 4y agoFair point. I look for books in a certain genre, though. I find myself retreating to classics that are over 30 years old, because the new stuff is so unreadable. I'll probably start The Black Company (for like, the twentieth time), soon.
- setgree 4y agoIn the great short books category, Willa Cather’s plains trilogy books are like 150-200 pages each, they’re fast reads and the prose is excellent — I’d start with ‘O Pioneers!’
- djdhrbrh 4y agohttps://www.btb.termiumplus.gc.ca/tpv2guides/guides/pep/index-eng.html?lang=eng&page=punct_2_commas_that_clutter 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
- ChrisMarshallNY 4y agoHey, 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.
- euroderf 4y agoOn the other hand American English LOVES periods, leading to visual abominations like N.A.T.O.
- YeGoblynQueenne 4y ago> 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 people who enter science fiction generally receive more messaging about fiction writing as a sole source of income than, say, people entering mainstream fiction. The messaging there is different: get an MFA, teach; it’s understood that your teaching position supports your career as a writer. For writers entering science fiction, that’s not really a thing yet. We’re maybe getting there, but the messaging they receive is mostly: Be very prolific. https://culture.org/an-interview-with-ted-chiang/ https://culture.org/an-interview-with-ted-chiang/ >> As [Stephen King] got more and more famous, he started being able to bully his editors, to the point where his work is barely edited at all. Yeah, I kinda noticed that too. I picked up a book of his and couldn't finish it because it felt like every episode in the story was written so that it took maybe ten, maybe fifty more pages than it really needed to. Extreme padding. I think Liu Cixin also went through something similar. The Dark Forest was lean and mean. The next two books were progressively fatter and more verbose and full of aimless meandering. Though maybe that was an attempt to complete a trilogy to capitalise on the first book, if I'm more cynical.
- jacksnipe 4y agoWhile I see where you’re coming from re: The Three Body Problem Vs the rest of the series, the core ideas in the Dark Forest and Deaths End are so exciting that I can’t help but feel the rest of the story is a justification for exploring them.
- YeGoblynQueenne 4y agoOops- I meant The Three Body Problem was lean and mean Thanks!
- JJMcJ 4y ago> 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.
- eatonphil 4y ago> 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.
- JJMcJ 4y agoThese days shorter fiction is almost always published as part of a collection, unless you are selling on line or self publishing in print.
- eatonphil 4y agoIs this in response to the wrong comment? I'm giving an example of the opposite of what you're saying.
- JJMcJ 4y agoWhat 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 hour show without losing too much of the interesting details.
- eatonphil 4y agoYou can literally buy these as paperback though, directly from the publisher: https://www.penguinrandomhouse.com/series/IMA/inspector-maigret https://www.penguinrandomhouse.com/series/IMA/inspector-maig....
- JJMcJ 4y agoOf 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.
- lkxijlewlf 4y agoI can only read his short fiction with few exceptions. He got to the point where he would take 50 pages (exaggeration, but still...) to describe, I dunno, a room. Okay, so the room is important, but is it that important?
- warrenm 4y agoI've never read King, but do recall the hilarity of Goldman's "The Princess Bride: S. Morgenstern's Classic Tale of True Love and High Adventure, The "Good Parts" Version" ""editorial' comments throughout ... like "with this and that, we move to chapter 4"
- larsrc 4y agoThat's not just him, it seems to happen to a lot of authors when they get famous. They get more clout and can push back on the editors, or the editors become afraid to cut too much, and suddenly you have bricks where half the words could be removed.
- bombcar 4y agoYou can see it in action by looking at a boxed Harry Potter set.
- JJMcJ 4y agoIf 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.
- rleigh 4y agoYou can see exactly the same with other authors. Asimov and J. K. Rowling, to pick two obvious candidates. Compare "Foundation" with "Foundation and Earth" or "Foundation's Edge". Or "The Philosopher's Stone" with "The Order of the Phoenix". The former were well-edited and succinct. The latter were overly long, in some cases sorely repetitive with large amounts of padding, and a good editor could have cut them down by at least half without losing much. And let's not even get into Robert Jordan... Even the best authors need an editor.
- warrenm 4y ago>Even the best authors need an editor. I've worked as a reviewer/editor (with "compensation" in the form of the acknowledgment page) on a handful of technical books Overall, of the ~7 authors I've reviewed/edited, I can confidently assert only one was wrong, but ALL wrote in nearly-unfollowable ways
- randomcarbloke 4y agoEh, depends...as you point out it is becoming a "lost art". The average quality of editors is utterly abysmal, so if you're pretty handy with style, or have lived under the cosh of an academic style guide for long enough you can probably get by without an editor.
- warrenm 4y ago>lived under the cosh of an academic style guide for long enough you can probably get by without an editor. I'd say the opposite As someone who's recently been put back under the "cosh of an academic style guide", I can definitely say the "academic style guide" does NOTHING to help with editing ... it's all about FORMAT Format is nice, and all ... but almost 100% irrelevant to the content
- randomcarbloke 4y agoThen it's a lost cause, you can't expect an editor to understand content, their function is to impose style, any reasonable exposure to formal language should be sufficient (but actually I disagree completely). If major publications can't employ decent editors what hope have you?
- k__ 4y agoGrammarly is still better than no editor.
- ghaff 4y agoIMO not by much. I mean, it catches out and out errors which is something I guess. And it gives some generally applicable feedback about excessive use of passive voice, overly long sentences, etc. But for the most part it doesn't really improve your writing in terms of structure, clarity, etc.
- no_identd 4y agoNot really: https://web.archive.org/web/20170816111301/http://serenity-software.com/pages/comparisons.html https://web.archive.org/web/20170816111301/http://serenity-s... https://web.archive.org/web/20170619192710/http://www.serenity-software.com/pages/brute_force.html https://web.archive.org/web/20170619192710/http://www.sereni... Too bad Serenity Software appears AWOL.
- warrenm 4y agoI still use Grammarly in my browser, but had to turn it off on my phone and elsewhere ... it's a great idea of a tool ... but ends up being unworkable too often :(
- ducharmdev 4y agoI think many people write off empathy as being about warm and fuzzy feelings, and don't realize that it's a very useful skill that can be improved with practice. The more effectively you can imagine perspectives other than your own, the more easily you can come up with creative solutions, communicate well, and overall just be a more pleasant person to be around.
- pieno 4y ago> The absolute, invariable first rule in tech writing is to know your audience. While that’s definitely true for tech writing generally, I feel it’s usually not the best advice for someone wanting to improve their technical writing. Tech writing is first and for all “writing”. I feel that’s where a lot of people are struggling already: they may know vocabulary and grammar, but they have difficulties to write a well structured text. Even a single paragraph consisting of two or three sentences can be very hard for many people to actually think about. They may have been focusing on “shortcut” rules such as “maximum X words per sentence” or “maximum Y sentences per paragraph”. But those are more often than not a distraction to actually think about a logically structured text. It’s important to have a narrative to guide the reader through the text, presenting new pieces of information in a logical sequence, and anticipating how a reader could misunderstand what you’re trying to say. For fiction writers, coming up with a narrative feels natural (even if it still can be hard). However, non-fiction writers may not even realise that they need some kind of narrative. You do need to know your audience to anticipate how your reader could misunderstand your text, but I think it’s best to start practising by writing for yourself or someone like yourself. Write something about a topic you know pretty well, but do not master perfectly. Then, read what you’ve written one or two weeks later, and see if it still makes sense to you. If some parts seem confusing, try improving them. You could do the same with texts written by someone else: whenever you think the text is confusing or unclear, try improving itself. Do not just quickly add a word or sentence that specifically addresses your confusion, but take a step back and try to understand what caused the confusion. Try to really think about the order in which information is presented, whether that information is explained clearly, and whether all information in your text is necessary to understand the point you’re making.