write for one person
125 points by lalitm
125 points by lalitm
This is good advice. I also feel that it is skipping a few steps in the process that a lot of people struggle with.
Honestly even just writing for yourself, it's good to properly introduce subjects. It ensures you know what you're talking about well enough to write about it and ensures clarity of thinking on your end.
That’s a good advice, but for me most writing is about a thing that happened and making the reader participate in a recreation of the (sometimes mystery) story, which naturally starts more introductory.
So I still try to write to a single person, but I try to spark this person’s interest which almost always means starting with at least a bit of shared understanding before jumping into the deep end (which I think of more as triggering the right page fault in the reader's brain than explaining something from first principles).
Also, if you provide structure a reader can easily skim over details they are familiar with and over the deep stuff to the conclusions.
it’s a bit funny to see this here. This is part of a short series of comics on how I write from some years ago. It never grew into a zine but there’s also:
and a couple of blog posts I probably wrote around the same time:
I completely agree. One tremendous part of the art of communication is understanding shared context. You can say the same thing using 2 or 30 sentences depending on what your level of shared context is.
Also, not every piece of content has to be aimed at beginners. That's totally fine.
I think people take this idea from scientific papers, where you are often required to introduce the reader to a topic, even if you're going to do a complete deep dive into some nitty-gritty detail (as in, every scientific paper ever). I have no idea why this is so commonplace there, but it always grated on me.
While an introduction for an outsider doesn't always serve much purpose, indeed, introducing the topic is still useful because it implicitly synchronises terminology and ensures the reader knows what perspective the writer has on the topic, and which parts of it they care about. This is especially helpful for papers that don't "simply" give an incremental improvement on something but present some new idea, that typically involves some cross-subject-area language.
Yeah it's actually something I really enjoy when writers do. Like one of my favorite physics textbooks is Feynman & Hibbs, which is a treatment of the path integral formulation of quantum mechanics.
It opens with two chapters that basically introduce quantum mechanics and then the formulation from first principles, even though the reader is probably an advanced undergraduate who has studied the subject for several years. It certainly doesn't need to do this, but it does, and it's so good because of it.
What this does is kind of magical, as the rest of the book becomes incredibly easy to follow (even though it's very technical) as you have the correct framing and terminology fresh in your in mind. There's so much clarity, very far from what reading an advanced textbook in quantum physics is generally like.
A textbook by definition needs to be "complete", so it makes sense if it spends some time covering familiar ground to get to the meatier parts. A paper doesn't have that requirement (and it would be weird if it did).
Consider that a paper may be read by a person maybe decades in the future. The implicit circumstances that may be obvious to the writer and reader if they're close in time might not be readily apparent.
In an academic paper the introduction serves as a place to cite prior work. Without this, it's ambiguous as to what parts of what you are saying is novel and your own work versus prior work.
Also fields are so specialised sometimes that someone in an adjacent field might need to read a bunch of your citations to understand your paper / what point you are making.
These introductions rarely provide enough context for an outsider to read and digest your paper properly.
Simon Peyton Jones says that an introduction is for stating the problem and listing the paper’s contributions. The survey of prior work should mostly go after the bulk of the paper, because it’s easier to compare after reader knows the details. (But cite other work when relevant earlier in the paper.)
It makes sense to include a brief summary of the field, as a sort of map, leading up to the place where your contribution lies. What I find annoying is when the authors try to go over basic stuff themselves, as in actually "introducing" the details to the reader rather than deferring to other papers. This invariably fails to serve its purpose, as it's typically too summarized for a complete newbie and too basic for those who came here to read the paper for its innovation.
When I was at university, I took a very good class on academic, technical, and professional writing. Among many other things, the instructors emphasised that to write effectively, we should start with a clear audience in mind, and write for their level of knowledge. Having a good idea of our audience also helps us have a good idea of how motivated someone would be to read what we write, and how hard we'd have to work to keep them engaged. Different audiences require incompatible trade-offs.
If you're writing about your own original research in a very specific field, you might be writing for just a handful of people (other researchers in that field), but you can be sure all of them will be very interested in what you write (so you can prioritise directly sharing new information over making your writing accessible). Conversely, if your audience is more general, you likely need to work harder to keep them engaged, and prepare to introduce concepts that you know a lot about, but they probably don't. You'd also need to omit some details. If you tried to write for both of those audiences at the same time, it probably wouldn't be effective for either.
I feel that "write for one person" is basically that, but more catchy :)
This may apply to some niche blogs. But if you write a documentation or give lectures or write a book... the single material is usually consumed by people with different knowledge. Of course, even the documentation, lecture or book should focus on certain target group – however there is still significant spread in knowledge levels.
I see the solution rather in sensible structuring that allows skipping already known parts and fast navigation to desired information.