Markdown style guide
Paul Graham on Good Writing
I think if you pointed to a random paragraph in anything written by anyone and told them to make it slightly shorter (or longer), they'd probably be able to come up with something better.
The best analogy for this phenomenon is when you shake a bin full of different objects. The shakes are arbitrary motions. Or more precisely, they're not calculated to make any two specific objects fit more closely together. And yet repeated shaking inevitably makes the objects discover brilliantly clever ways of packing themselves. Gravity won't let them become less tightly packed, so any change has to be a change for the better.
If you have to rewrite an awkward passage, you'll never do it in a way that makes it less true. You couldn't bear it, any more than gravity could bear things floating upward. So any change in the ideas has to be a change for the better.
Writing that sounds good is more likely to be right for the same reason that a well-shaken bin is more likely to be tightly packed. But there's something else going on as well. Sounding good isn't just a random external force that leaves the ideas in an essay better off. It actually helps you to get them right.
the easier the essay is to read, the easier it is to notice if something catches
the rhythm of good writing has to match the ideas in it, and ideas have all kinds of different shapes. Sometimes they're simple and you just state them. But other times they're more subtle, and you need longer, more complicated sentences to tease out all the implications
when an essay sounds good, it's not merely because it has a pleasing rhythm, but because it has its natural one. Which means you can use getting the rhythm right as a heuristic for getting the ideas right. And not just in principle: good writers do both simultaneously as a matter of course. Often I don't even distinguish between the two problems. I just think Ugh, this doesn't sound right; what do I mean to say here?
The sound of writing turns out to be more like the shape of a plane than the color of a car. If it looks good, as Kelly Johnson used to say, it will fly well.
It's only when you're writing to develop ideas that there's such a close connection between the two senses of doing it well
The way to write something beautiful and false is to begin by making yourself almost believe it. So just like someone writing something beautiful and true, you're presenting a perfectly-formed train of thought. The difference is the point where it attaches to the world. You're saying something that would be true if certain false premises were.
So it's not quite right to say that better sounding writing is more likely to be true. Better sounding writing is more likely to be internally consistent. If the writer is honest, internal consistency and truth converge.
ideas are tree-shaped and essays are linear. You inevitably run into difficulties when you try to cram the former into the latter. Frankly it's suprising how much you can get away with. But even so you sometimes have to resort to an endnote.
Obviously if you shake the bin hard enough the objects in it can become less tightly packed. And similarly, if you imposed some huge external constraint on your writing, like using alternating one and two syllable words, the ideas would start to suffer
There are two senses in which writing can be good: it can sound good, and the ideas can be right. It can have nice, flowing sentences, and it can draw correct conclusions about important things. It might seem as if these two kinds of good would be unrelated, like the speed of a car and the color it's painted. And yet I don't think they are. I think writing that sounds good is more likely to be right.
So here we have the most exciting kind of idea: one that seems both preposterous and true. Let's examine it. How can this possibly be true?
You can't simultaneously optimize two unrelated things; when you push one far enough, you always end up sacrificing the other. And yet no matter how hard I push, I never find myself having to choose between the sentence that sounds best and the one that expresses an idea best. If I did, it would be frivolous to care how sentences sound. But in practice it feels the opposite of frivolous. Fixing sentences that sound bad seems to help get the ideas right.
Carl Zimmer on writing: “Don’t make a ship in a bottle”
To write about anything well, you have to do a lot of research. Even just trying to work out the chronology of a few years of one person’s life can take hours of interviews. If you’re writing about a scientific debate, you may have to trace it back 100 years through papers and books. To understand how someone sequenced 400,000 year old DNA, you may need to become excruciatingly well acquainted with the latest DNA sequencing technology.
Once you’ve done all that, you will feel a sense of victory. You get it. You see how all the pieces fit together. And you can’t wait to make your readers also see that entire network of knowledge as clearly as you do right now.
That’s a recipe for disaster.
When I was starting out, I’d try to convey everything I knew about a subject in a story, and I ended up spending days or weeks in painful contortions. There isn’t enough room in an article to present a full story. Even a book is not space enough. It’s like trying to build a ship in a bottle. You end up spending all your time squeezing down all the things you’ve learned into miniaturized story bits. And the result will be unreadable.
It took me a long time to learn that all that research is indeed necessary, but only to enable you to figure out the story you want to tell. That story will be a shadow of reality—a low-dimensional representation of it. But it will make sense in the format of a story. It’s hard to take this step, largely because you look at the heap of information you’ve gathered and absorbed, and you can’t bear to abandon any of it. But that’s not being a good writer. That’s being selfish. I wish someone had told me to just let go.
Find time to write at least a couple hours a day, every day. And I mean real writing, not dithering on the Internet telling yourself you’re doing “research.” Get a blank notebook and a pen if you have to. It’s in those long stretches of time with your own words, sentences, and paragraphs that you come face to face with all the great challenges of writing, and you find the solutions.
Six Tips on Writing from John Steinbeck
Abandon the idea that you are ever going to finish. Lose track of the 400 pages and write just one page for each day, it helps. Then when it gets finished, you are always surprised.
Forget your generalized audience. In the first place, the nameless, faceless audience will scare you to death and in the second place, unlike the theater, it doesn’t exist. In writing, your audience is one single reader. I have found that sometimes it helps to pick out one person—a real person you know, or an imagined person and write to that one.
If a scene or a section gets the better of you and you still think you want it—bypass it and go on. When you have finished the whole you can come back to it and then you may find that the reason it gave trouble is because it didn’t belong there.
If there is a magic in story writing, and I am convinced there is, no one has ever been able to reduce it to a recipe that can be passed from one person to another. The formula seems to lie solely in the aching urge of the writer to convey something he feels important to the reader.
a bad story is only an ineffective story.
On the Accountability of Unnamed Public Relations Spokespeople
When a statement is attributed to “a spokesperson” from a company or institution, the world doesn’t know who that spokesperson is. Only the reporter or writer, and perhaps their editors. There is an explicit lack of accountability attributing statements to an institution rather than to specific people. We even have different pronouns — it’s institutions that do things, but only people who do things. Who is the question.
This West Point / ProPublica near-fiasco has me reconsidering my skepticism toward The Verge’s obstinacy on this. It occurs to me now that The Verge’s adamancy on this issue isn’t merely for the benefit of their readers. Putting one’s name on a statement heightens the personal stakes. This is why it’s more than vanity to put your name on your work, whatever your work is — it shows you take responsibility for its validity
Write Like You Talk
You don't need complex sentences to express complex ideas. When
specialists in some abstruse topic talk to one another about ideas
in their field, they don't use sentences any more complex than they
do when talking about what to have for lunch. They use different
words, certainly. But even those they use no more than necessary.
And in my experience, the harder the subject, the more informally
experts speak. Partly, I think, because they have less to prove,
and partly because the harder the ideas you're talking about, the
less you can afford to let language get in the way.
Informal language is the athletic clothing of ideas
I'm not saying spoken language always works best. Poetry is as much
music as text, so you can say things you wouldn't say in conversation.
And there are a handful of writers who can get away with using fancy
language in prose.
But for nearly everyone else, spoken
language is better.
After writing the first draft, try explaining to a friend what you
just wrote. Then replace the draft with what you said to your friend.
Is Every Picture Worth 1,000 Words?
The phrase a picture is worth a thousand words has two popular origin stories. One version credits advertising executive Frederick R. Barnard, who attributed the phrase to an ancient Chinese proverb.
The closest Chinese equivalent translates to “Hearing something a hundred times isn’t better than seeing it once.” In other words, the Chinese Origin was made up:
“…the Chinese derivation was pure invention. Many things had been thought to be ‘worth ten thousand words’ well before pictures got in on the act;”
the true origin of the proverb is not Chinese but adspeak.3 It shows how the phrase has morphed into a commercial, facile cliche.
Letting images and pictures compete for supremacy reduces the complex relationship between images and words into a direct, quantifiable comparison. Words and images function differently
A few carefully chosen words can say what 1,000 stock images cannot. The right image can counter cynicism, closed-mindedness, or an automatic dismissal of a convincing argument.
Tell your audience how you interpret the image. What the image means.
Use images to complement, not repeat or overshadow, the text. Get rid of images that are just there to add color.
Stock images are clichés. Clichés can be easily turned on their head because of their simplistic topic. You want to communicate that you’re diverse and you end up telling people that you’re a company run by a minority. Or you want to communicate success, but the focus on two middle-aged white people ends up communicating their privilege.
Whether you like it or not, people will read into this picture as well and they won’t find a lot of valuable or advantageous information in it. It again mostly says: “This boring website thinks that I don’t see that this is a meaningless stock image.”
Pictures have an impact when they tell a story that only a picture can tell.
A good image tells a good story
Forget trying to decide what your life’s destiny is. That’s too grand. Instead, just figure out what you should do in the next 2 years.
Visuals can stir up feelings or paint a scene in an instant. However, they may not always nail down the details or explain things as clearly as words can.
Words can be very precise and give you all the information you need. Yet, sometimes they miss that instant impact or emotional punch.
For each visual you add to your presentation, you should ask yourself “What does it really say?” And then check:
Does it enhance the meaning of my message, or is it purely decorative?
Does it belong at this point in my presentation? Would it be better for another slide?
Is there a better image that says what I want to say?
Computers don’t feel, and that means: they don’t understand what they do, they grow images like cancer grows cells: They just replicate something into the blue. This becomes apparent in the often outright creepiness of AI images.
AI is really good at making scary images. Even if the prompt lacks all hints of horror kitsch, you need to get ready to see or feel something disturbing when you look at AI images. It’s like a spell. Part of the scariness comes from the cancer-like pattern that reproduces the same ornament without considering its meaning and consequence.
Placing pictures next to each other will invite comparisons. We also compare images that follow each other. Make sure that you do not inadvertently compare apples and oranges.
When placing multiple images in a grid or on one slide after the other, ensure they don’t clash in terms of colors, style, or resolution. Otherwise, people will focus more on the contrast between the images rather than their content.
Repeating what everyone can see is bad practice. To make pictures and text work, they need to have something to say about each other.
Don’t write next to the image what people already see. A caption is not an ALT text.
The most powerful combination of text and image happens when the text says about the image what you can’t see at first sight, and when the image renders what is hard to imagine.
Do not be boring or overly explanatory. The visual should attract their attention to your words and vice-versa.
If a visual lacks meaning, it becomes a decorative placeholder. It can dilute your message, distract from what you want to say, and even express disrespect to your audience.
On Openings Essays, Conferences Talks, and Jam Jars
how to write better openings and introductions / intros in non-fiction writing
The beginning is almost never the most compelling or important part. It's just the bit you thought of first, based on your subjective chronology.
Signposting what you're going to write about is good, but starting with an exhaustive list of definitions is extremely boring.
Invoking paleolithic people is an overplayed way to convince us your topic is cosmically important.
Openings need tension – paradoxes, unanswered questions, and unresolved action
Good openings propose problems, pose questions, drop you into an unfinished story, or point at fundamental tensions within a topic. Ideally within the first paragraph or two.
"Good writing starts strong. Not with a cliché ("Since the dawn of time"), not with a banality ("Recently, scholars have been increasingly concerned with the questions of..."), but with a contentful observation that provokes curiosity."A Sense of StyleStephen Pinker
Creating tension in non-fiction work is trickier because your story is (hopefully) constrained by reality. You are not at liberty to invent suspicious murders, salacious extramarital affairs, or newly-discovered-magical-powers to create tension and mystery. You have to deal with the plain, unexotic facts of the world.
Your job becomes much harder if you pick topics with no tension, problems, or puzzles within them. To paraphrase Williams, it is more of a failure to pose an uninteresting problem, than to poorly articulate an interesting one
Your interest in the topic is your best directional clue for finding the tension or interesting paradox. Your urge to write about the thing hopefully comes from a place of curiosity. You have unanswered questions about it. It feels important or consequential for unexplained reasons. You think you've seen things in it other people haven't. Pay attention to that interest.
Problems are a destabilising condition that has a cost for a community of readers that needs a solution. Destabilising condition is just a fancy word for “change” here – a change in the status quo. Put another way, a problem is an expected turn of events, that has undesireable consequences, for an audience who will care about it, that we want to explore solutions to.
Williams is speaking to a community of academic writers in his book. They're trying to present scientific and research problems in plain, objective language, which isn't necessarily what we want to do with narrative writing like blogging or personal essays.
We have a little more liberty to put interesting padding around the change, consequences, and solution, such as telling an opening anecdote, or drawing readers in with characters, rich details, and sensory descriptions.
Williams suggests we try to state our problem and then ask a series of so what?'s to get at the underlying problem
For your writing to be worth reading, you need to be exploring something of consequence for someone
When McPhee writes, after first immersing himself in his raw material (field notes, interview transcripts, official documents) for weeks, he then draws a structure for the work. The structure lays out the major themes and scenes he'll work through, in the order that will make them most compelling and coherent.
Developing a structure requires navigating the tension between chronology and theme. Chronology is what we default to, but themes that repeatedly appear want to pull themselves together into a single place. The themes that really matter should be in your opening. Even if the moment that best defines them happens right before the end of the timeline.
An alternative to the bullshit industrial complex
Stop spamming the em dash everywhere | Mikołaj Biernat
15 rules for blogging, and my current streak