Common bugs in writing (2021)
cs.columbia.edu
cs.columbia.edu
Sometimes, particularly in didactic material, it helps to explain things in more than one way, as different people may find different explanations helpful.
As they say every rule has its exceptions and I think all three variants can be suitable.
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.
The executives and the sponsors care about business objectives and they are going to zone out as soon as you start getting into the weeds.
Tell them what you are going to tell them.
Tell them what you want to tell them.
Tell them what you just told them.
"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.
Ie “STAR format”
In the hero's tale it kind of starts of happy and then something goes wrong. STAR misses out half of the story. It's like if Shrek started just before the wedding with a narrative explanation of the problem Shrek was trying to solve.
I think tables of content are great for live presentations, especially if your slides have some indicator where we are currently. It's just too easy to get lost or slide away, especially in engaging and thought provoking presentations. That way I can get back to where we are, where we come from and where we're headed.
But I agree that it's super annoying to actually present that stuff multiple times. It should be a navigational device, not content.
> 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.
‘Each paragraph should have a lead sentence summarizing its content. If this doesn't work naturally, the paragraph is probably too short.’
My writing is also aimed at different audiences simultaneously. I have to address the same subject different ways.
font-family: arial,verdana,sans-serif;
font-size: small;
chuckles nervously in Lisp
Maybe it's the nesting that's the problem? Like, refactor it out into its own function/paragraph?
font-size: 1.2rem;
Font size looks fine to me on Firefox/Android.
https://web.archive.org/web/20011225094629/https://www.cs.co...
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.
edit: also for me the font size is set to 12, not 14
Verdict: too small.
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.
Are you aware of any academic writing focused extensions for Vale? In specific, I would need different "style" as it's called on Grammarly.
There are three rules for writing. Unfortunately nobody knows what they are. —W. Somerset Maugham
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).
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.
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]
I'm disappointed. I specifically mentioned how the book is applicable across academic fields, because I suspected the typical HN poster would be in sci/tech and would have a bias against the social sciences. Sometimes I hate being proven correct.
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.
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.
I like using https://www.ctan.org/pkg/diffcoeff for this.
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).
This might ease tensions among those who disagree with these choices or with prescriptive rules for writing in general.
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.
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')
> 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.
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.
A very common bug in writing is misspelling the contraction of 'it is' as 'its'.
>14. Use until instead of the colloquial till.
To add to the 'see also' list, the Australian Government Style Manual (https://www.stylemanual.gov.au) is another great reference.
> 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 , which … doesn't exist. Is that the joke, or did the link rot?
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.
• 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
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."