Not everyone can do that. Especially young people or when one just starts writing, it’s hard to even get anyone to care let alone thing enough about what you’re writing to improve it.
In my experience the next best thing is to forget about it for a week, and then re-read the text.
Given the comments left by @healeycodes and @jakob here, perhaps there’s merit to staring a lobste.rs “proofreading group”? I know we have several authors here that regularly post their articles; perhaps they would benefit from having them reviewed. I worry that the generous proofreading offers in this thread may eventually be forgotten or go unnoticed by the people who’d benefit from them.
I like this idea of a thread that you and @rustybolt suggested! In my opinion, something weekly would be good. Perhaps it can be posted on Mondays, so that people writing over the weekend can get feedback soon after?
I’d like to say I’d also like to read and review technical writing. I also write occasionally – mostly quite mathy stuff.
Also, maybe it’s a good idea to start a weekly “who’s writing?” thread where we can all post stuff and review each others’. Alternatively we can start an old-school mailing list (or even just a group mail would work, where everyone just replies to all on the latest one, then everyone could send feedback in private – this has the disadvantage that it wouldn’t be visible on lobste.rs so it would be hard for new people to join).
I agree that it’s hard (especially when starting out) to find people to read your technical writing before publishing it.
To anyone reading this comment: I’m happy to review your technical writing and provide feedback.
(You can find my email via my website’s about page.)
The last time I posted this on here, I read about some really cool topics and concepts, as well as new experiences, that I would have not read otherwise!
In my experience the next best thing is to forget about it for a week, and then re-read the text.
This helps me. However, it’s hard to step away from a piece of writing that is exciting for you!
That’s a kind offer, and I’m happy to see it being made. I feel quite indebted to the wonderful community here, so I will offer the same. I am also happy to review your technical writing and provide feedback. Similarly, my email address can be found on my website.
I was going to post the same thing! You can be your own affordable second set of eyes. Time is a safe way to clear your head. A lesser alternative is to work on another significant mental problem while not thinking of the sitting draft, so that when you look back at your draft, your mind is somewhat clear and you can review.
I request a follow up post where an existing blog post is rewritten to show how it could be improved!
Even better, I’d like to see the author of this post show a finished blog post, and the process of getting there from an imperfect original? How do you debug a blog post?!
I was thinking about doing something like this back in January.
If anyone has a blog post they would like me to edit, feel free to send it my way (e-mail, PM, etc.). If I think it can be improved and it overlaps with my areas of interest / knowledge, I could either offer suggestions, or rewrite it myself (although I do have a lot of my own posts to write, so no promises).
Warning: I’ll likely delete 50% of the words in the post while retaining the meaning. My last editing pass almost always consists of deleting words.
And I suppose you should be comfortable showing the before-and-after, because that’s the request here. (And of course I’ll be interested if anyone thinks the “after” version is worse :) )
For context, I’ve received a lot of good feedback on the technical writing in my blog:
This is a great write up! I wish I saw more of these types of posts
Another warning is that good writing requires more effort / more rewrites than most people are willing to put in. Unfortunately I’ve backed off on that for the last couple years, but I want to get back to it. It’s good to know that you can do it if you put enough time in, even if you’re not always willing or able to.
So it would be ideal if you have a lot of time to spend on one blog post (and that might be true for more people now due to the state of the world.)
Not just technical people are bad at this, neither. Communicating effectively is difficult in every context. We don’t always say what we mean; abstract concepts are even harder to talk about than something you can touch.
How do you debug a blog post?!
I used to be very harsh with editing whenever somebody asked me about writing in college…
I would actually disagree about jokes. I’ve read several posts here that, while being superb in quality, were made less appealing due to the inclusion of jokes. The most ‘severe’ offender is Kindness for Mean Girls. I found the humor to be simply a distraction from the actual content of the article, which to me was far more interesting and engaging. Similarly, the jokes in the recent CRDT series, while not nearly as emphasized, seemed unnecessary. I loved both articles - but to me, the jokes weren’t an improvement.
I appreciate written articles and books because the pace at which you go through them is entirely your own. You’re fee to read faster or slower, and to take breaks. If I wanted to take a breather, I would simply pause reading. This would happen on my own terms, as opposed to being enforced on me at a point where the author deems it necessary to sprinkle some humor.
I also suspect that the points at which ‘breathers’ are necessary depend a lot on the prior experience of the reader. If I wanted to read something on type theory of operational semantics, there’s a good chance I wouldn’t need to pause. If, on the other hand, I tried to read the same content 2 years ago, I’d probably need to stop after every sentence. Rather than diluting the content of the post with jokes and funny images to help 2-years-ago me (who is perhaps the lowest target for any technical article, really), I’d prefer that authors didn’t make assumptions about what would be easy for me and what would be hard.
The good bit about extra stuff is that you can easily skip it. I’m sure lengthy pieces like books and articles can benefit of a more formal structure but posts (as in blog posts) that is characterless wall of text with some formatting sprinkled in is big pass for me. If I want that I can get a book or read the docs which are not gonna be outdone by a short blog post.
Inserting blurbs, jokes and other extras is far from being some sort of new concept. If you open up any decent education book you’d notice it’s filled with quotes, info blurbs, illustrations and often even jokes.
I don’t think it’s that easy to skip extra stuff. At the very least, it requires you too look and see whether or not the piece of info is relevant. That alone takes some cognitive effort.
If you open up any decent education book you’d notice it’s filled with quotes, info blurbs, illustrations and often even jokes.
I mostly disagree about jokes (and joke images in particular, as described in your original comment). Could you please give an example of such a book? I’m having trouble thinking of a book I recently read that featured a noticeable amount of jokes. My sample is rather obscure; the books that I’ve read (and found very good) in the past couple of years are:
Types and Programming Languages
Implementing Functional Languages: a tutorial
Static Program Analysis
The Cambridge Handbook of Computer Science Education
Logical Foundations
Visual Explanations (not in its entirety)
I’m not quite sure what you mean by “education book”. The Cambridge Handbook is a book about education. I dare say it’s quite good; however, I do not remember it including any jokes. The rest of the books in the list are meant to teach a subject, and they all do not include jokes, either (or much of anything “extra”, really).
That’s not to say that technical articles can’t be funny. However, rather than dropping an image between paragraphs with a pun or somewhat relevant joke like the Mean Girls article I linked, I think it’s more tasteful to imbue the technical content with humor. The example that comes to mind is from the paper A Taste of Linear Logic by Philip Wadler. Linear logic concerns the distinction between propositions with exactly one use, and propositions with an infinite number of uses. Wadler walks through some examples of this concept, but uses “I have money”, “I can buy pizza”, and “I’m happy” as propositions, leading to amusing claims such as “Infinite pizza does indeed lead to infinite happiness”. This is funny, but it still advances the reader’s understanding. The problem here is that doing so requires a lot more thought and writing / rewriting, like @andyc points out above.
I do completely agree about illustrations being essential to educational material. It’s one thing to talk about lattices and order, but it’s a whole another to provide a picture to make it clear what it all means. However, I think images are essential for their explanatory value, rather than their effect on the “weight” of the post. If text intimidates the reader, then they have a nice side effect of reducing text density; however, this is not their primary purpose.
As Antoine de Saint-Exupery once said,
Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
I think jokes, for the most part, can be taken away.
I don’t like most jokes/memes in technical writing, but I like to give the reader some air with one or more examples. I like to include examples that should be trivial to understand if the reader understood everything in the more technical/theoretical part. Chances are (s)he didn’t, and can improve (or ‘debug’, if (s)he misunderstood something) his/her understanding with the example.
The essay doesn’t cover the most important way to improve your technical writing: have someone else read a draft. You can’t see your own blind spots.
Not everyone can do that. Especially young people or when one just starts writing, it’s hard to even get anyone to care let alone thing enough about what you’re writing to improve it.
In my experience the next best thing is to forget about it for a week, and then re-read the text.
Given the comments left by @healeycodes and @jakob here, perhaps there’s merit to staring a lobste.rs “proofreading group”? I know we have several authors here that regularly post their articles; perhaps they would benefit from having them reviewed. I worry that the generous proofreading offers in this thread may eventually be forgotten or go unnoticed by the people who’d benefit from them.
What about a “What are you writing?” thread? It could be created on a weekly/monthy basis, where people share drafts and ask other members to comment.
I like this idea of a thread that you and @rustybolt suggested! In my opinion, something weekly would be good. Perhaps it can be posted on Mondays, so that people writing over the weekend can get feedback soon after?
I’d like to say I’d also like to read and review technical writing. I also write occasionally – mostly quite mathy stuff.
Also, maybe it’s a good idea to start a weekly “who’s writing?” thread where we can all post stuff and review each others’. Alternatively we can start an old-school mailing list (or even just a group mail would work, where everyone just replies to all on the latest one, then everyone could send feedback in private – this has the disadvantage that it wouldn’t be visible on lobste.rs so it would be hard for new people to join).
I agree that it’s hard (especially when starting out) to find people to read your technical writing before publishing it.
To anyone reading this comment: I’m happy to review your technical writing and provide feedback.
(You can find my email via my website’s about page.)
The last time I posted this on here, I read about some really cool topics and concepts, as well as new experiences, that I would have not read otherwise!
This helps me. However, it’s hard to step away from a piece of writing that is exciting for you!
That’s a kind offer, and I’m happy to see it being made. I feel quite indebted to the wonderful community here, so I will offer the same. I am also happy to review your technical writing and provide feedback. Similarly, my email address can be found on my website.
Same!
An alternative I’ve found that works (for me at least) is to wait a couple of weeks, print the page, and read it very carefully.
I was going to post the same thing! You can be your own affordable second set of eyes. Time is a safe way to clear your head. A lesser alternative is to work on another significant mental problem while not thinking of the sitting draft, so that when you look back at your draft, your mind is somewhat clear and you can review.
I request a follow up post where an existing blog post is rewritten to show how it could be improved!
Even better, I’d like to see the author of this post show a finished blog post, and the process of getting there from an imperfect original? How do you debug a blog post?!
I was thinking about doing something like this back in January.
If anyone has a blog post they would like me to edit, feel free to send it my way (e-mail, PM, etc.). If I think it can be improved and it overlaps with my areas of interest / knowledge, I could either offer suggestions, or rewrite it myself (although I do have a lot of my own posts to write, so no promises).
Warning: I’ll likely delete 50% of the words in the post while retaining the meaning. My last editing pass almost always consists of deleting words.
And I suppose you should be comfortable showing the before-and-after, because that’s the request here. (And of course I’ll be interested if anyone thinks the “after” version is worse :) )
For context, I’ve received a lot of good feedback on the technical writing in my blog:
https://old.reddit.com/r/programming/comments/7xlca1/commonmark_is_a_useful_highquality_project/
Another warning is that good writing requires more effort / more rewrites than most people are willing to put in. Unfortunately I’ve backed off on that for the last couple years, but I want to get back to it. It’s good to know that you can do it if you put enough time in, even if you’re not always willing or able to.
So it would be ideal if you have a lot of time to spend on one blog post (and that might be true for more people now due to the state of the world.)
I should also point out that I borrowed a CSS rule or two from http://bettermotherfuckingwebsite.com/ :)
http://www.oilshell.org/css/all-2020.css
You could try linting your blog post: https://www.gnu.org/software/diction/
Works ok for me.
This is an awesome idea! Something like https://motherfuckingwebsite.com/!
Not just technical people are bad at this, neither. Communicating effectively is difficult in every context. We don’t always say what we mean; abstract concepts are even harder to talk about than something you can touch.
I used to be very harsh with editing whenever somebody asked me about writing in college…
I have an obligation to mention http://bettermotherfuckingwebsite.com/ as well.
What a great post, however I feel it didn’t mention a very important idea: give some space for readers to breathe!
Technical blogs tend to be quite long and information packed, inclusion of some illustrations or even joke images can make a big difference.
I would actually disagree about jokes. I’ve read several posts here that, while being superb in quality, were made less appealing due to the inclusion of jokes. The most ‘severe’ offender is Kindness for Mean Girls. I found the humor to be simply a distraction from the actual content of the article, which to me was far more interesting and engaging. Similarly, the jokes in the recent CRDT series, while not nearly as emphasized, seemed unnecessary. I loved both articles - but to me, the jokes weren’t an improvement.
I appreciate written articles and books because the pace at which you go through them is entirely your own. You’re fee to read faster or slower, and to take breaks. If I wanted to take a breather, I would simply pause reading. This would happen on my own terms, as opposed to being enforced on me at a point where the author deems it necessary to sprinkle some humor.
I also suspect that the points at which ‘breathers’ are necessary depend a lot on the prior experience of the reader. If I wanted to read something on type theory of operational semantics, there’s a good chance I wouldn’t need to pause. If, on the other hand, I tried to read the same content 2 years ago, I’d probably need to stop after every sentence. Rather than diluting the content of the post with jokes and funny images to help 2-years-ago me (who is perhaps the lowest target for any technical article, really), I’d prefer that authors didn’t make assumptions about what would be easy for me and what would be hard.
The good bit about extra stuff is that you can easily skip it. I’m sure lengthy pieces like books and articles can benefit of a more formal structure but posts (as in blog posts) that is characterless wall of text with some formatting sprinkled in is big pass for me. If I want that I can get a book or read the docs which are not gonna be outdone by a short blog post.
Inserting blurbs, jokes and other extras is far from being some sort of new concept. If you open up any decent education book you’d notice it’s filled with quotes, info blurbs, illustrations and often even jokes.
I don’t think it’s that easy to skip extra stuff. At the very least, it requires you too look and see whether or not the piece of info is relevant. That alone takes some cognitive effort.
I mostly disagree about jokes (and joke images in particular, as described in your original comment). Could you please give an example of such a book? I’m having trouble thinking of a book I recently read that featured a noticeable amount of jokes. My sample is rather obscure; the books that I’ve read (and found very good) in the past couple of years are:
I’m not quite sure what you mean by “education book”. The Cambridge Handbook is a book about education. I dare say it’s quite good; however, I do not remember it including any jokes. The rest of the books in the list are meant to teach a subject, and they all do not include jokes, either (or much of anything “extra”, really).
That’s not to say that technical articles can’t be funny. However, rather than dropping an image between paragraphs with a pun or somewhat relevant joke like the Mean Girls article I linked, I think it’s more tasteful to imbue the technical content with humor. The example that comes to mind is from the paper A Taste of Linear Logic by Philip Wadler. Linear logic concerns the distinction between propositions with exactly one use, and propositions with an infinite number of uses. Wadler walks through some examples of this concept, but uses “I have money”, “I can buy pizza”, and “I’m happy” as propositions, leading to amusing claims such as “Infinite pizza does indeed lead to infinite happiness”. This is funny, but it still advances the reader’s understanding. The problem here is that doing so requires a lot more thought and writing / rewriting, like @andyc points out above.
I do completely agree about illustrations being essential to educational material. It’s one thing to talk about lattices and order, but it’s a whole another to provide a picture to make it clear what it all means. However, I think images are essential for their explanatory value, rather than their effect on the “weight” of the post. If text intimidates the reader, then they have a nice side effect of reducing text density; however, this is not their primary purpose.
As Antoine de Saint-Exupery once said,
I think jokes, for the most part, can be taken away.
I don’t like most jokes/memes in technical writing, but I like to give the reader some air with one or more examples. I like to include examples that should be trivial to understand if the reader understood everything in the more technical/theoretical part. Chances are (s)he didn’t, and can improve (or ‘debug’, if (s)he misunderstood something) his/her understanding with the example.