3 ms·

I agree with your "deeper claim", which is why I think the inverted pyramid is good for technical content. It tells you up front what the text is about and lets

I agree with your "deeper claim", which is why I think the inverted pyramid is good for technical content. It tells you up front what the text is about and lets you know if you should invest more time reading it. (It's the structure used in all academic publications for this reason.) If I was writing this post my intro would be something like (I'm writing this quickly so it won't be elegant, but the structure is in place): Yosh Wuyt recently posted an argument in favour of moving away from poll_next in the async next project. I disagree with this position. In this post I'm going to argue in favour of keeping poll_next and finalizing AsyncIterator. Specifically, I argue that poll_next has a simpler conceptual model requiring only a single state machine, better supports pinning, and works better with cancellation. This introduction gives the structure up-front so the reader can quickly decide if they want to continue. This actually makes me more excited to read the post because I like technical details, and this introduction is promising them. In the actual post the introduction doesn't tell me any specifics about what is to come and so does not motivate me to read further.

xpe 3y ago
Wait: it seems that you are not conveying what the inverted pyramid practically entails. For a reader it means: start at the front, proceed linearly, and stop reading at any point because you what follows will be, by construction, “less important”. For an editor, therefore, cut wherever you want to meet a space limit. This premise of ordering by solely by “importance” as defined by the author is fundamentally flawed. It stands in conflict with detailed, logically organized, skimmable writing. (I think this could be proved mathematically by assuming some fairly obvious points about human nature, but that is for another time. The sketch would be: how to optimize the linearization of a topic graph using varying reader {preferences and knowledge graphs} as the metric.) Again, I’m not disagreeing with topic sentences. That idea is independent.
- noelwelsh 3y ago
  What I mean is 1) putting the most important things first and 2) adding sufficient signposts to make the structure of the document clear without having to read everything. I think a strict ordering by importance, which would make a document a kind of simultaneous recursive elaboration of all its points, would be unreadable for a document that, like this one, also has an element of explanation. I think this takes the essence of the inverted pyramid, but if you want to take a definition that is stricter then I'm fine to concede it's not.
xpe 3y ago
Thanks for writing this! I agree this would be clearer.

xpe 3y ago

Wait: it seems that you are not conveying what the inverted pyramid practically entails. For a reader it means: start at the front, proceed linearly, and stop reading at any point because you what follows will be, by construction, “less important”. For an editor, therefore, cut wherever you want to meet a space limit. This premise of ordering by solely by “importance” as defined by the author is fundamentally flawed. It stands in conflict with detailed, logically organized, skimmable writing. (I think this could be proved mathematically by assuming some fairly obvious points about human nature, but that is for another time. The sketch would be: how to optimize the linearization of a topic graph using varying reader {preferences and knowledge graphs} as the metric.) Again, I’m not disagreeing with topic sentences. That idea is independent.

noelwelsh 3y ago
What I mean is 1) putting the most important things first and 2) adding sufficient signposts to make the structure of the document clear without having to read everything. I think a strict ordering by importance, which would make a document a kind of simultaneous recursive elaboration of all its points, would be unreadable for a document that, like this one, also has an element of explanation. I think this takes the essence of the inverted pyramid, but if you want to take a definition that is stricter then I'm fine to concede it's not.

xpe 3y ago

Thanks for writing this! I agree this would be clearer.