[HN Gopher] Common Bugs in Writing (2021)
___________________________________________________________________
Common Bugs in Writing (2021)
Author : pablode
Score : 174 points
Date : 2023-06-24 09:25 UTC (13 hours ago)
(HTM) web link (www.cs.columbia.edu)
(TXT) w3m dump (www.cs.columbia.edu)
| Jedd wrote:
| > ... work out what you wanted to say, even if its a whole paper.
|
| A very common bug in writing is misspelling the contraction of
| 'it is' as 'its'.
| Wistar wrote:
| ... another I see a lot is alot.
| jwilk wrote:
| https://hyperboleandahalf.blogspot.com/2010/04/alot-is-
| bette...
| Narishma wrote:
| The less said about 'would of' and 'should of' the better.
| bogtog wrote:
| On a somewhat different note, does anybody have suggestions on
| books/videos to help learn thoroughly grammar? My PhD advisor
| sometimes uses words like "past participle", and I just nod along
| as though I understand what he is referring to. I have an eBook
| of Strunk & White sitting around, but I figured it was more about
| general good writing than grammar specifically.
| spondylosaurus wrote:
| Check out _Dreyer 's English: An Utterly Correct Guide to
| Clarity and Style_. The eponymous Dreyer is chief copyeditor at
| Random House, so he knows his way around a dependent clause
| (and isn't afraid to show it), but his writing style is
| engaging and not at all dry. At times, if you can believe it,
| he's even pretty funny.
| coliveira wrote:
| Take a class on English grammar. This is a solved problem.
| ajkjk wrote:
| But they asked about books and videos.
| mtlynch wrote:
| Strunk & White doesn't really cover grammar if I recall.
|
| I like _The Bedford Handbook_ by Diana Hacker. I had to buy it
| for a course in college, and I 've found it to be a helpful
| reference for grammar rules. The explanations are clear, and
| there are helpful examples for each concept.
| joegahona wrote:
| Readable and fun, but extremely useful:
|
| * Lapsing into a Comma, Bill Walsh (RIP)
|
| * The 10% Solution, Ken Rand (for editing down wordy text)
|
| * Sin and Syntax, Constance Hale
|
| * Woe Is I, Patricia T. O'Conner
|
| More resource-like and grammar-heavy:
|
| * Words Into Type, Marjorie E. Skillin (hard-core grammar
| rules, great section on redundancies)
|
| * Chicago Manual of Style (in general, the core style of book
| and magazine writing)
|
| * Associated Press Stylebook (in general, the core style of
| newspaper writing)
|
| * Garner's Modern English Usage, Bryan A. Garner
|
| * Merriam-Webster's Dictionary of English Usage
|
| * Dictionary of American Idioms, Maxine Tull Makkai
|
| Not about writing, but hilarious and snobby and awesome --
| great airplane reading:
|
| * The Big Book of Beastly Mispronunciations, Charles Harrington
| Elster
| tptacek wrote:
| This suffers from a pathology common to writing style guides: it
| starts with strong, reasonably universal advice, and descends
| into a subjective catalog of the author's pet peeves. There's no
| utility in advising technical writers not to begin sentences with
| the word "and".
| idlewords wrote:
| Especially if the preceding sentence is always true.
| xdavidliu wrote:
| One of my pet peeves is when the writer uses a pronoun
| immediately after a sentence with multiple proper nouns. For
| example, something like "Biden ran against Trump in 2020, and he
| raised a lot of money".
| rmasters wrote:
| This kind of ambiguity is rampant in technical writing.
| Example: "There are situations where developers do X instead of
| Y which is the wrong thing to do." Wait, is X wrong or Y?! You
| go ahead and assume X is wrong and then figure out later they
| meant Y is wrong or vice versa. Argh!
| dmckeon wrote:
| Or, "the packet is sent from the client to the server, and it
| ...." I see this a lot in technical writing where the writer is
| explaining a flow of code or data, and is very well aware of
| the antecedent of it - but the reader now has to guess, read
| ahead, perhaps discover they were wrong, revert their mental
| model, and make a different guess. JRY - Just repeat yourself.
| Be unambiguous. Use whatever word would have been the
| antecedent of the pronoun, and let clarity shine thru.
| MengerSponge wrote:
| This is a funny mixture of "things that are easily fixed with a
| LaTeX library" and "things that are challenging because good
| writing is hard"
|
| If you write in LaTeX, check out {SIunitX} and {cleveref}.
|
| Also, it's not on this list, but a pet peeve of mine: math mode
| (italics) should be used for variables and indices. Abbreviations
| or names shouldn't be set in math mode. For example, the
| probability of hacker news P sub H should be set as
| $P_\mathrm{H}$, because H is a name, and not a
| variable/parameter.
|
| Relatedly, differentials shouldn't be italicized. Its
| \int\mathrm{d}x, not \int dx.
| adrianmsmith wrote:
| > Relatedly, differentials shouldn't be italicized. Its
| \int\mathrm{d}x, not \int dx.
|
| Interesting. I went to school in the late 80s in the UK. As an
| adult, I was convinced I'd been taught as a child that the d of
| dx should not be italicised, as only variables like x should be
| italicised. But when I checked that belief, I couldn't really
| find any evidence that that was, or ever had been, the case. I
| had assumed until I read your comment that I'd misremembered
| it.
|
| If I google for "integration" or "differential equations", and
| click on the images tab, every result without exception has the
| d italicised (at least for me).
| bradrn wrote:
| > Relatedly, differentials shouldn't be italicized. Its
| \int\mathrm{d}x, not \int dx.
|
| I like using https://www.ctan.org/pkg/diffcoeff for this.
| erehweb wrote:
| One extremely common bug even among good writers - saying "Jack
| was in his 30th year" to mean "Jack was 30" (and so should be in
| his 31st year). At least, I think of this as a bug, but perhaps
| it is accepted by general convention? I have not seen any
| discussion of it.
| luispauloml wrote:
| >14. Use until instead of the colloquial till.
|
| I remember reading somewhere that "till" is actually older then
| "until", and that they are perfectly interchangeable, although I
| do see "until" way more often than the other.
| cratermoon wrote:
| Many archaic forms are still perfectly valid English, and some
| of them don't even seem all that odd. Modern English Usage is
| always changing, though, and unless you're writing period-
| appropriate dialog, it's best to avoid archaisms.
| smitty1e wrote:
| I tend toward sprawling sentences. Later edits see those chopped
| up. Also, one is sparing with the pronouns. They are variables on
| the stack of the reader's mind, but quickly become a tangle.
| Lacerda69 wrote:
| Vale is an OSS tool that you can use as a "prose linter" with
| many of these rules. You can also write your own rules. Together
| with a spellchecker its a good replacement for proprietary tools
| like grammarly.
|
| - https://github.com/errata-ai/vale
| Jhsto wrote:
| This is interesting, I integrated it into my blog straight
| away, thanks!
|
| Are you aware of any academic writing focused extensions for
| Vale? In specific, I would need different "style" as it's
| called on Grammarly.
| cratermoon wrote:
| All the styles I've been able to find are geared towards
| technical writers creating software documentation. Is there a
| particular academic style guide you have in mind, perhaps it
| would be possible to create a vale style for it.
| Lacerda69 wrote:
| Yea that is true, I use a customized version of the write-
| good and Microsoft styles, but for math formulas and such
| something like latex is better IMO ( though possible to
| recreate with vale too probably)
| 3pt14159 wrote:
| I'm a little perplexed as to why professors and other academic
| staff have routinely hard to read websites. Yes I'm aware I can
| bump up the font size, but especially on mobile that gets
| annoying. It's one thing if they don't have a stylesheet what so
| ever, it's a fully another thing to intentionally make things
| hard to read: font-family: arial,verdana,sans-
| serif; font-size: small;
|
| From an article that expressly advocates not making things hard
| to read: "Avoid excessive parenthesized remarks as they make the
| text hard to read;"
| coliveira wrote:
| Because they have better things to do than tinkering with the
| latest HTML technology.
| skilled wrote:
| font-size: 1.2rem;
|
| that is considered the latest HTML technology?
| DistractionRect wrote:
| A lot of sites haven't kept up with best practices. Even HN
| doesn't (I'm on mobile so I can't double check, but last I
| did HN uses "pt").
| [deleted]
| layer8 wrote:
| "Internet Explorer is a popular web browser. The current
| version number is 5.0." might explain it.
| cratermoon wrote:
| Yes and the doctype is "<!DOCTYPE HTML PUBLIC "-//W3C//DTD
| HTML 3.2 Final//EN">", and there's inline style at "<body
| bgcolor=white>". Even though the footer says "last updated
| 2021" and there are links dated 2015, I suspect the page is
| otherwise unchanged from its initial late-90s/early 2000s
| design.
| 8organicbits wrote:
| Hmm. IE 5.0 and IE 5.5 were released in 1999, so perhaps the
| first version was written then. I also see a citation from
| 2015, which is a strong signal this was edited in or after
| 2015.
|
| Font size looks fine to me on Firefox/Android.
| layer8 wrote:
| The first version on the Internet Archive is from 2001,
| where the design made sense more or less, and it hasn't
| changed much since then.
|
| https://web.archive.org/web/20011225094629/https://www.cs.c
| o...
| Solvency wrote:
| You're saying this on a website that I need to manually zoom in
| to 200% in order to remotely read the text.
| Someone1234 wrote:
| HN uses a font size of 14px, that's only slightly smaller
| than most browser's baseline of 16px (Vs. 12px for small). By
| any chance are you reading it on a 4K display?
|
| In my opinion, HN and most websites, shouldn't be setting a
| baseline font size at all (least of all in pixels).
| Medium/default should be the baseline then large/larger etc
| should be used as-needed.
| siriusfeynman wrote:
| it's smaller than most other websites and for me on a 1080p
| display top level comments don't wrap until ~200 characters
| at the default zoom level which makes it even worse
|
| edit: also for me the font size is set to 12, not 14
| Solvency wrote:
| - Too small on a 13" MacBook Pro (2019) - Too small on a 15"
| MBP (2019) - Too small on a 32" 4K BenQ desktop monitor on
| Windows.
|
| Verdict: too small.
| taopai wrote:
| > Avoid excessive parenthesized remarks as they make the text
| hard to read
|
| _chuckles nervously in Lisp_
| stirfish wrote:
| *chuckles nervouthly*
|
| Maybe it's the nesting that's the problem? Like, refactor it
| out into its own function/paragraph?
| [deleted]
| bjornasm wrote:
| I have grown to like it. I found it really perplexing like you
| but now I view it as they just want to present their
| information in the rawest, most simple way possible. I was been
| inspired by it when I made my personal website, however I added
| some responsiveness etc to increase the usability a bit.
| eviks wrote:
| Those who don't know...
| mrbabbage wrote:
| the font size isn't ideal, but I find the line width to be a
| far larger problem.
|
| a traditional book will have around 70 characters per line [1].
| by contrast, on my screen (13" M1 macbook air at default screen
| resolution and browser zoom), suggestion 5 has 231 (!!)
| characters on its first line.
|
| [1] https://en.wikipedia.org/wiki/Line_length
| nayuki wrote:
| I would like to add, "Common mistakes when using the metric
| system": https://www.nayuki.io/page/common-mistakes-when-using-
| the-me...
| NoboruWataya wrote:
| There are loads of these lists out there and they are all largely
| making the same points.
|
| They are useful and I definitely think that people who are
| serious about writing prose should read them. But there are few
| (if any) stylistic rules that I would consider absolute. To me,
| these rules are useful to know so that, when you are about to
| break one, you can ask yourself "do I have a good reason for
| breaking this rule?". If not, redraft.
| idlewords wrote:
| I try to post this advice in every similar thread: if you want to
| get better at communicating information through writing, then _On
| Writing Well_ by William Zinsser is really worth your time.
| dillydogg wrote:
| I enjoyed Writing Well and think my writing improved as a
| result. Another useful book is Christopher Lasch's Plain Style.
| JadeNB wrote:
| I didn't understand the significance of
|
| > 35. ... Other words should be banished.
|
| (all other words than cliches? Certain other words, so obvious
| that they need not be specified?), so I followed the link
| http://www.lssu.edu/banished , which ... doesn't exist. Is that
| the joke, or did the link rot?
| jamesgill wrote:
| For god's sake, ignore rules for writing. Except the ones that
| end up making you money. --Mark Twain
|
| There are three rules for writing. Unfortunately nobody knows
| what they are. --W. Somerset Maugham
| P-Nuts wrote:
| Rule 24 doesn't obey rule 11. Practice what you preach!
| mo_42 wrote:
| When I was doing my PhD, I was really in love with such guides.
| There is also the book Bugs in Writing by Lyn Dupre.
|
| Looking back I'm not so sure about the utility in scientific
| writing. Every research community has its own jargon. If don't
| stick to it, you're going to have a hard time.
|
| Today, I very much enjoy these again because most writing happens
| in a blog.
|
| I would add to that list (not original from me):
|
| - Dangling comparison: if you use the comparative, you need to
| name both things. Counter example: "On Saturdays, it's better to
| stay in bed longer". Better than what? Longer than what?
|
| - Adjectives: don't use them in technical writing unless they
| have a specific meaning (e.g., very likely was defined as a
| certain probability threshold before).
| ReactiveJelly wrote:
| Longer than when it's not a Saturday
| atahanacar wrote:
| Longer than staying in bed shorter when it's a Saturday.
| cratermoon wrote:
| > When I was doing my PhD
|
| What field, if I may ask?
|
| There's an article titled "Writing higher education
| differently: a manifesto on style" by Helen Sword
| <http://dx.doi.org/10.1080/03075070802597101> advocating for
| academic writers to "express complex ideas clearly and
| succinctly; write with originality, imagination and creative
| flair; convey enthusiasm, commitment and a strong sense of
| self; tap into a wide range of intellectual interests; avoid
| excessive jargon; employ plenty of concrete examples and
| illustrations; demonstrate care for their readers; and know how
| to tell a good story"
|
| Also, academics may appreciate the book _Writing for Social
| Scientists_ , by Howard S. Becker. This is true even if your
| field is is not social science. You can probably safely skim
| most of the chapter on "Writing With Computers", as it was
| first written in 1986 (back when typewriters were being
| replaced with "word processors") and revised in 2007.
| mo_42 wrote:
| > What field, if I may ask?
|
| It was in CS actually. So writing in social sciences doesn't
| seem too appropriate.
|
| Thanks for the other hint though. Seems quite interesting and
| seems similar to: How to write a great research paper [1]
|
| [1] https://m.youtube.com/watch?v=WP-FkUaOcOM
| gala8y wrote:
| Slightly OT, but sticking to E-Prime makes writing really
| powerful.
|
| https://en.wikipedia.org/wiki/E-Prime
| bradrn wrote:
| > Avoid use of passive tense if at all possible. Example: "In
| each reservation request message, a refresh interval used by the
| sender is included." reads better and shorter as "Each ...
| message includes ..."
|
| To which I submit the following article as a rebuttal:
| http://www.lel.ed.ac.uk/~gpullum/passive_loathing.html. Oh well,
| at least this person seems somewhat more consistent than most in
| following his own rule.
| ape4 wrote:
| There must be places for reasonable use of the passive. Not
| everything is advertising copy.
| KineticLensman wrote:
| One reasonable place is a description of a method ('software
| was developed') where identifying the actor isn't important.
|
| Active voice is much better in situations such as contracts
| where the identity of actors is critical (e.g. 'X is
| responsible for writing the software while Y will maintain
| the software after delivery')
| joegahona wrote:
| There are. I worked as a copy editor in consumer publications
| and dreaded editing one particular guy's stuff because he
| took the "no passive voice" thing as gospel and really went
| through contortions to observe it. His copy had a really
| harsh and jagged tone as a result. Other editors who were
| aware of the "rule" but weren't strident about it had writing
| that was so much more enjoyable to read.
|
| These days I'm working with engineers and product managers in
| a very technical environment, and the passive voice is
| everywhere, so I find myself rewriting a lot, and rewriting
| improves it. I'm not eradicating the passive voice, but
| people use it in a lot of places where it doesn't work well.
| spondylosaurus wrote:
| There certainly are. The Google Developer Documentation Style
| Guide includes some (imo, non-exhaustive) examples of when to
| use the passive voice[1]:
|
| > To emphasize an object over an action. > To de-emphasize a
| subject or actor. > If your readers don't need to know who's
| responsible for the action.
|
| Sometimes you end up twisting yourself into knottier
| linguistic pretzels trying to make something active (for
| active's sake) instead of just using the passive voice
| deliberately.
|
| https://developers.google.com/style/voice#exceptions
| zak1726 wrote:
| Could I just give this page to chatgpt and feed paragraph by
| paragraph my report and get it to be the most outstanding writing
| that has ever been
| teddyh wrote:
| Instead of this random collection of rules, I prefer Larry
| McEnerney's lecture _The Craft of Writing Effectively_ :
|
| https://www.youtube.com/watch?v=vtIzMaLkCaM
| JoshTriplett wrote:
| > If you find yourself saying "In other words," it means you
| didn't say it clearly enough the first time. Go back and rewrite
| the first attempt.
|
| Sometimes, particularly in didactic material, it helps to explain
| things in more than one way, as different people may find
| different explanations helpful.
| Errancer wrote:
| I agree, often I write first sentence in technical language to
| introduce the reader to the existing discussion and then say
| "In other words" to paraphrase the technical language into more
| familiar but less precise vocabulary.
| brookst wrote:
| I agree, but even in those cases, "in other words" is just
| throat-clearing. Like "simply put" or "that is to say", these
| are noise words that only hurt the clarity of writing.
|
| If two examples help, use two examples. There's no need to
| call out that the second one is another example; people will
| get that.
|
| At least that's how I see it after a lifetime of trying to
| stamp out this kind of filler language in my own writing.
| blowski wrote:
| Without beating around the bush, what I'm trying to say is,
| in other words, unless I'm mistaken, it's perhaps possible
| that maybe some writing just could be written in fewer
| words.
| ukuina wrote:
| Sir Humphrey Appleby, is that you?
| Errancer wrote:
| I agree with your description that this is a throat-
| clearing but I don't see why it hurts the clarity of
| writing. Dense texts packed with information can often
| benefit from such breaks. In general I find text which uses
| artefacts from spoken language more readable. There are
| limits to this of course but if we remove all redundancy we
| end up with dry text which sometimes is expected but I am
| unsure if it is the most readable or clear way to write.
| One side note is that it might be culture dependent.
| English speaking countries and Poland, where I am from,
| expect and teach much different writing style than France
| or Germany.
| dllthomas wrote:
| If it's two examples, it's not the same thing presented
| again in other words. If you are presenting the same thing
| twice phrased differently, separating the two presentations
| is important, and "in other words" is a perfectly
| reasonable phrase to do that.
| mo_42 wrote:
| I'd rather do the opposite. I'd start with the intuitive
| high-level idea and then introduce technical terms and
| formality to the prepared mind.
|
| As they say every rule has its exceptions and I think all
| three variants can be suitable.
| lostlogin wrote:
| Further down (39) there is a suggestion that you start a
| paragraph with a summary sentence. That might help cover this.
|
| 'Each paragraph should have a lead sentence summarizing its
| content. If this doesn't work naturally, the paragraph is
| probably too short.'
| ReactiveJelly wrote:
| Is that why those "explained at five different level" videos on
| YouTube are popular?
| tmoertel wrote:
| Agreed! When writing about challenging technical subjects, we
| ought to realize that a reader may not fully grasp one
| explanation, even if it's written clearly. Buttressing it from
| another angle can reconnect the reader with the intended
| meaning. For example, pairing formal and informal takes on a
| point seems to work well.
| jasonlotito wrote:
| This is a good example of why the list of rules is prefaced
| with this:
|
| > Like almost all rules, there are cases where breaking them is
| a good idea and seasoned writers may well object with "but"
| responses for some of these. Thus, consider the rules below as
| mental rumble strips - you should probably slow down and think
| if you encounter these cases.
| lelanthran wrote:
| It's a good rule for general information presentation.
|
| Tell them what you are going to tell them.
|
| Tell them what you want to tell them.
|
| Tell them what you just told them.
| IshKebab wrote:
| Ugh that "rule" has resulted in more terrible PowerPoint
| presentations than any other.
|
| "Hi, today I'm going to tell you about 1+1... 1+1=2... So
| what have we talked about? I started by telling you that
| 1+1=2."
|
| So much waffle.
|
| The best presentations I've heard don't do that at all. Yes
| they start by _setting the context and goal of the
| presentation_ , and they end with a _solid conclusion_. But
| they don 't have a table of contents at the start that people
| tediously read and then exactly the same thing again at the
| end.
|
| You might argue that that's not what it's meant to mean, but
| that is what people _hear_ so it 's bad advice.
|
| The best advice I've ever heard for presenting was from a
| stand up comedian who was teaching how to present well. His
| basic advice was to follow the classic Hero's Tale. Set the
| stage. Something goes wrong. You triumphantly overcome it.
|
| You might think that doesn't apply to technical presentations
| but you'd be surprised how often you can fit your story into
| that framework.
| teddyh wrote:
| Replace boring "context" with "showing why your writings
| and information will be valuable to the reader" and I think
| you've got something.
| IshKebab wrote:
| Yeah that's good advice.
| ajanuary wrote:
| To nitpick the nitpicky article, it was "OS X", not "OSX".
| kimburgess wrote:
| Excellent, concise guidelines.
|
| To add to the 'see also' list, the Australian Government Style
| Manual (https://www.stylemanual.gov.au) is another great
| reference.
| jmbwell wrote:
| This is a style guide for work done in CS at Columbia. Sometimes
| there are more than one way to do something and you just have to
| make a choice. Whatever choice you make, it should be documented.
| That documentation is called a style guide. This is that document
| for this group.
|
| This might ease tensions among those who disagree with these
| choices or with prescriptive rules for writing in general.
___________________________________________________________________
(page generated 2023-06-24 23:01 UTC)