10 ms·
Common bugs in writing (2021)
- kimburgess 3y agoExcellent, concise guidelines. To add to the 'see also' list, the Australian Government Style Manual (https://www.stylemanual.gov.au https://www.stylemanual.gov.au) is another great reference.
- MengerSponge 3y agoThis 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.
- bradrn 3y ago> Relatedly, differentials shouldn't be italicized. Its \int\mathrm{d}x, not \int dx. I like using https://www.ctan.org/pkg/diffcoeff https://www.ctan.org/pkg/diffcoeff for this.
- adrianmsmith 3y ago> 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).
- Lacerda69 3y agoVale 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 https://github.com/errata-ai/vale
- Jhsto 3y agoThis 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 3y agoAll 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 3y agoYea 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)
- cratermoon 3y agoThere are quite a few academics using a markdown->latex pipeline, with pandoc or similar tools. But it doesn't seem like the vale linter is the right tool when it comes to formulae.
- 3pt14159 3y agoI'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;"
- taopai 3y ago> Avoid excessive parenthesized remarks as they make the text hard to read chuckles nervously in Lisp
- stirfish 3y ago*chuckles nervouthly* Maybe it's the nesting that's the problem? Like, refactor it out into its own function/paragraph?
- deleted 3y ago[deleted]
- coliveira 3y agoBecause they have better things to do than tinkering with the latest HTML technology.
- skilled 3y agofont-size: 1.2rem; that is considered the latest HTML technology?
- DistractionRect 3y agoA 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").
- P-Nuts 3y agoRule 24 doesn’t obey rule 11. Practice what you preach!
- bradrn 3y ago> 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 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 3y agoThere must be places for reasonable use of the passive. Not everything is advertising copy.
- KineticLensman 3y agoOne 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')
- spondylosaurus 3y agoThere 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 https://developers.google.com/style/voice#exceptions
- joegahona 3y agoThere 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.
- JoshTriplett 3y ago> 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 3y agoI 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.
- mo_42 3y agoI'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.
- brookst 3y agoI 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.
- Errancer 3y agoI 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.
- mo_42 3y agoWhen I was doing my PhD, I was really in love with such guides. There is also the book Bugs in Writing by Lyn Dupré. 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 3y agoLonger than when it's not a Saturday
- atahanacar 3y agoLonger than staying in bed shorter when it's a Saturday.
- cratermoon 3y ago> 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 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.
- 3y ago
- xdavidliu 3y agoOne 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 3y agoThis 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 3y agoOr, "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.
- xdavidliu 3y agoanother pet peeve I have is double or even triple negatives used casually. Newspapers like the NYTimes or Wall street journal are very guilty of this. For example: "The congressman voted down a bill banning opposition to Foo". Of course, this statement is factual, but it's extremely difficult to tell whether the congressman is in favor of Foo or not. Simply contracting the sentence to "The congressman (doesn't?) like Foo" loses info. I think the proper solution here is for the newspaper to have the original confusing sentence, but also add a second sentence with the contraction as a hint. For example: "The congressman voted down a bill banning opposition to Foo. He did this because he is in favor of Foo."
- smitty1e 3y agoI 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.
- NoboruWataya 3y agoThere 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.
- bogtog 3y agoOn 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.
- coliveira 3y agoTake a class on English grammar. This is a solved problem.
- ajkjk 3y agoBut they asked about books and videos.
- mtlynch 3y agoStrunk & 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.
- spondylosaurus 3y agoCheck 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.
- joegahona 3y agoReadable 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
- idlewords 3y agoI 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 3y agoI enjoyed Writing Well and think my writing improved as a result. Another useful book is Christopher Lasch's Plain Style.
- Jedd 3y ago> ... 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'.
- nayuki 3y agoI would like to add, "Common mistakes when using the metric system": https://www.nayuki.io/page/common-mistakes-when-using-the-metric-system https://www.nayuki.io/page/common-mistakes-when-using-the-me...
- luispauloml 3y ago>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 3y agoMany 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.
- mock-possum 3y agoI prefer ‘til personally, makes it a bit more explicit what word you’re using.
- ajanuary 3y agoTo nitpick the nitpicky article, it was “OS X”, not “OSX”.
- nayuki 3y agoAnd that naming is obsolete since macOS 10.12 (year 2016). https://en.wikipedia.org/wiki/MacOS_Sierra https://en.wikipedia.org/wiki/MacOS_Sierra
- jamesgill 3y agoFor 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
- tptacek 3y agoThis 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 3y agoEspecially if the preceding sentence is always true.
- gala8y 3y agoSlightly OT, but sticking to E-Prime makes writing really powerful. https://en.wikipedia.org/wiki/E-Prime https://en.wikipedia.org/wiki/E-Prime
- teddyh 3y agoInstead of this random collection of rules, I prefer Larry McEnerney’s lecture The Craft of Writing Effectively: https://www.youtube.com/watch?v=vtIzMaLkCaM https://www.youtube.com/watch?v=vtIzMaLkCaM
- gala8y 3y agoThanks, just started watching it. Interesting.
- erehweb 3y agoOne 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.
- zak1726 3y agoCould 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
- jmbwell 3y agoThis 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.
- JadeNB 3y agoI didn't understand the significance of > 35. … Other words should be banished. (all other words than clichés? Certain other words, so obvious that they need not be specified?), so I followed the link http://www.lssu.edu/banished http://www.lssu.edu/banished , which … doesn't exist. Is that the joke, or did the link rot?