> 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.
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.
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.
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.
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.
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.
In my experience, that’s a mistake. I start off by framing things in the “why” for a high level conceptual understanding and slowly get into the weeds.
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.
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.
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.
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.
> 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.
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.
Kind of, but STAR is boring and there's generally no emotional journey. You just start with the problem and then it's immediately solved.
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 agree. I’m often on conference calls with customers where the audience make up have different backgrounds and concerns - finance, security, compliance, operations, developers, etc.
My writing is also aimed at different audiences simultaneously. I have to address the same subject different ways.
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:
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.
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.
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.
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.
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
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.
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.
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.
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)
There 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.
When 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).
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.
> writing in social sciences doesn’t seem too appropriate.
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.
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.
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.
> 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).
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.
> 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 ..."
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')
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.
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.
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.
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.
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.
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".
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.
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.
(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?
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.
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.
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.
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".
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.
another 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."
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!
Sometimes, particularly in didactic material, it helps to explain things in more than one way, as different people may find different explanations helpful.