11 ms·
What I think about when I edit (2019)
- deleted 3y ago[deleted]
- tosh 3y ago> Don’t use adverbs
- richrichie 3y agoIndeed!
- hubraumhugo 3y agoAny other engineers trying to improve their writing skills? Any additional resources or tips to help me refine my drafting and editing process?
- deleted 3y ago[deleted]
- thangalin 3y agoAnything by Diana C. Reep. Technical Writing: Principles, Strategies, and Readings is particularly insightful: https://www.amazon.ca/dp/0205721508 https://www.amazon.ca/dp/0205721508
- spit2wind 3y agoStrunk & White is always good to thumb through: https://archive.org/details/TheElementsOfStyle4thEdition https://archive.org/details/TheElementsOfStyle4thEdition The Wikipedia has links to other copies, like on Project Gutenberg.
- MrVandemar 3y agoDeath Sentence - The Decay of Public Language, by Don Watson. Blisteringly good. Not aimed at technical writers, but encourages you to think about how to really use language effectively and robustly.
- lawn 3y agoI've been trying to improve by making a conscious effort to practice it. I've been trying to blog and even wrote a book, partly to increase my writing skills. The book that helped me the most is On Writing Well: The Classic Guide to Writing Nonfiction. I also wrote a blog post about some of the lessons I learned: https://www.jonashietala.se/blog/2023/11/25/writing_lessons_learned_after_writing_a_book/ https://www.jonashietala.se/blog/2023/11/25/writing_lessons_...
- RheingoldRiver 3y agoDeveloping Quality Technical Information - https://www.amazon.com/Developing-Quality-Technical-Information-Handbook/dp/0133118975 https://www.amazon.com/Developing-Quality-Technical-Informat... My review + some notes - https://river.me/blog/book-review-quality-technical-information/ https://river.me/blog/book-review-quality-technical-informat... (it's very good)
- ndand 3y agoGoogle has a few courses about technical writing for engineers: https://developers.google.com/tech-writing https://developers.google.com/tech-writing
- beezlebroxxxxxx 3y agoThere are innumerable sources online for improving technical writing and they all generally repeat the same conventions and "rules". I tend to warn people, though, that over fixating on technical writing will not make you a great writer but just a capable technical writer. If you're looking to improve your writing in general, then I think Joseph Williams' "Style: Towards Clarity and Grace" is the single best book on the subject written so far. Rather than simply state certain "rules", it methodically workshops examples to show how you can write and rewrite a sentence to change your meaning and emphasis at will.
- richrichie 3y agoI can’t recommend Strunk and White’s Elements of Style enough.
- probably_wrong 3y agoNot a source, but rather an exercise: give yourself a tight word count and rework your essay until it fits. When one third of your article has to go, you start looking really deep into how to extract as much value as possible out of every word.
- remoquete 3y agoEva is a fellow technical writer. I'm glad to see tech writers get visibility in here.
- dijksterhuis 3y ago> Whitespace is key for technical documentation but can also be used to great effect in blog posts, emails, and elsewhere. It’s hard for people to read long paragraphs, especially on a computer screen. They will zone out. 100%. The explanation (?) I first heard which helped me 'get' this whitespace principle was along the lines of > Have you reached a page in a book with no paragraph breaks and thought 'oh no'?
- avg_dev 3y agoYou know, I kind of feel this way about code too. Sometimes people don’t put in a lot of blank lines to break things up and I find that a little harder to read and a bit more intimidating than reading with a few blank lines between concepts/actions. In fact, I was thinking after I read the article, maybe many of these principles apply to writing maintainable code too.
- KineticLensman 3y agoI was a doc reviewer in my corporate past life and found myself using many of these guidelines. I’d add one more: don’t use different names for the same thing. Many of the docs I reviewed had multiple authors and quite often they used slightly different terminology. This really complicated things for readers. I eventually realised there was a meta-principle here: in tech writing, the reader should never have to resolve ambiguity created by the authors.
- berkes 3y agoThis gets even worse in software code. When "Naming things" is hard, and two people name the same thing, they'll very likely give it a different name. A guarantee to maintenance nightmares. DDD by Eric Evans suggests using Ubiquitous Language. Even when I don't use anything from DDD, I always add a dictionary.md in which we write down the domain terms. What is a Customer? What does a "Loan Application" mean. What can we do to a loan application and how do we call those actions? It's one of the easiest tricks, that dictionary.md, but with great effect.
- valenterry 3y agoWhy not put those definitions into the code, next to the types that define those entities?
- medstrom 3y agoYour term may not map cleanly to a single OOP class, and it may also be used in other function/variable names. There's also how you will express yourself in the code comments. I mean, I'm guessing the dictionary is not just for nouns, but also verbs and adverbs. What will "transact" usually mean in this codebase? What will "safely" mean?
- ffsm8 3y ago> Your term may not map cleanly to a single OOP class That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information. An argument against documenting it on the entities and functions would be that this would spread the information across the repository. The value you get from doing this in a single markdown file is the overview it provides, I think. These kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. And if it's just a comment on a file, it'll likely not even be seen
- jmmcd 3y agoI love this. Inevitably I want to make some improvements. > “He laughed with the kind of booming abandon that made the whole restaurant turn around and look.” The kind of? If it's a kind that exists generically then we can't have a past tense, so: “He laughed with the kind of booming abandon that *makes* the whole restaurant turn around and look.” But really, why emphasise it being generic? This is better: “He laughed with *a* booming abandon that made the whole restaurant turn around and look.” --- > Use lists where relevant, because it’s easier to read a bulleted list of items than to read a paragraph with the same information. Use lists only where all the items have the same status, in some sense. An ordinary paragraph can't be broken up into bullet points.
- wizzwizz4 3y agoIf it's a kind that existed generally, then we can have a past tense. "He laughed with the kind of booming abandon that made the whole restaurant turn around and look, in the before-times."
- jmmcd 3y agoWe now live in a sad, post-apocalyptic world, with no booming, no abandon, no turning around, and very few people in restaurants.
- coldtea 3y agoThis is hardly a bad description of the current state of affairs.
- coldtea 3y agoWe can describe "a kind that exists generally" even if the restaurant turned and looked (then) and would still turn (now and in the future). Just need to change "the" with "a": > He laughed with the kind of booming abandon that made the whole restaurant turn around and look. to: > He laughed with a kind of booming abandon that made the whole restaurant turn around and look. In this case his laugh is still described as having a generalized "booming abandon", but the reaction of the patrons isn't a necessary reaction to that "kind of" laughter, but to that particular instance of it. That is, the noun is "the kind of booming abandon" and not "the kind of booming abandon that made the whole restaurant turn around and look".
- richrichie 3y agoOriginal source found at: https://www.gutenberg.org/ebooks/37134 https://www.gutenberg.org/ebooks/37134
- richrichie 3y agoSome HN folks here are so thin skinned that they down vote a reference to Strunk and White?
- mattbee 3y agoIt's definitely nothing new but good advice bears repeating over the decades :) For big picture stuff on writing I also like "On Writing Well" by William Zissner and "First You Write A Sentence" by Joe Moran (which is a bit more British).
- svat 3y agoWas your comment (“Original source found at…”) intended to be a reply to some other comment, rather than being a top-level comment? Or did you actually mean to suggest that the original source of the post here (“What I think about when I edit (2019)”) is Strunk and White? The latter seems pretty misleading and inappropriate.
- Tomte 3y ago> You’ve heard this advice before. But you should understand why you shouldn’t use passive voice in your writing. It’s not just “bad style.” The ususal misunderstanding that everyone repeats. Read Williams‘, Clarity and Grace, or watch McEnerny‘s lecture on YouTube. Passive has its use, and it‘s not "to obscure who is doing the bad thing".
- alpinisme 3y agoWilliams’ book is really excellent. It deserves to be more widely read.
- microflash 3y agoIndeed. However, it is the most oft-repeated consequence of using Passive voice. In general, I use active voice and when it makes sense, passive voice is used as well.
- gghh 3y agoThanks for the references. I'll check them. I'm extremely biased against the business use of passive voice, to the point of getting so worked up when someone does it with me on mail or slack, that I need go to a quite room and relax for 5 minutes. The purchase order has been made. Your virtual machine has been created. I see this a lot in corporate environments, and it's by low level managers thinking every bit of information they're trusted with is so delicate and confidential, they must go above and beyond to reveal the least possible amount of it. Note, in the examples above, it was the manager themselves doing the action. What's wrong with "I did this", "I did that"? This is LARPing as CIA agents (or whatever), and they like the sound of it (I want you to know I have information I can't share, you little shit!). "I've just created your virtual machine" peasant "Your virtual machine has been created" special ops elite force management Mind you, 99.999% of the time, the concealment of "who did the thing" is totally unnecessary. It's only there to reinforce status.
- jodrellblank 3y agoThe opposite: "I've just created your virtual machine" - 3 year old, "mummy, mummy, /I/ did this! praise ME!". Got to insert yourself as the first thing in the sentence, as if the customer cares who did it. "Your virtual machine is ready" - Waiter, assistant, comfortable out of the limelight to let the focus be on the customer and what they are interested in. "I've just created your virtual machine" - You didn't make the deployment pipeline, you didn't build the hosting, or write any of the hypervisor or guest OS, you ran one script and now you're taking all the credit. Embarrassing.
- lootsauce 3y agoMy brain must be warped by using LLMs because I could not help but think that it would be an amazing prompt, complete with multiple examples of each principal. Perhaps good prompting is good writing?
- swayvil 3y agoI thought the same. (I did something similar in drawing. So it's a not uncommon path) Get your art sharp. Digest that into a science. Digest the science into automation. (And yes, one could argue that the result is a crystalline turd.)
- ano-ther 3y agoAll great advice. Except for “avoid passive”. It’s a part of the toolbox that changes the perspective on an action. “The pull request got merged” vs. “The maintainer merged the pull request”. If i want to talk about the new feature that gets implemented by the pull request, then I mislead the reader by emphasizing the maintainer, rather than the pull request. The passive also allows you to choose whether you want to call out the source of an action. “The pull request got merged by the maintainer.” Yes, you can misuse it to fudge responsibility, but you don’t need the passive to do that.
- medstrom 3y ago"They merged the pull request" sounds fine to me.
- coldtea 3y agoAs the parent notes though, "the passive also allows you to choose whether you want to call out the source of an action", while "they merged the pull request" does not.
- medstrom 3y agoThat part, I do not get. Do they mean it permits a rewrite? But all sentences do.
- coldtea 3y agoThey mean it allows you to not point out who did the merge. If the PR introduced a BUG or was a bad choice to merge it, you might not want to use an active form, because then you have to say who did it (for example, in a report), to protect them, or to not appear like you're pointing fingers. The passive voice allows you to state the fact that the commit was merged, without mentioning anybody. "John/Jil merged the pull request" vs "The pull request was merged" - you can chose whether you want to include "by John/Jil" or not.
- kd5bjo 3y ago
- RheingoldRiver 3y agoThis is a fantastic list of like, "suggestions to writers by editors" but I don't think it's a great list of "how to edit." The single most important thing when editing (imo) is "how can I preserve the author's voice?" Editing is not writing a new draft, it's amplifying the original.
- publius_0xf3 3y ago>One of the best writing tips I've ever gotten was to avoid using demonstrative pronouns. Instead of saying “this” or “that,” you should add a noun to spell out exactly what you’re referring to, even if you’ve just mentioned it. This piece of advice is maybe the only thing I remember from my college English class. A naked "this" or "that" now feels shamefully lazy to me.
- KineticLensman 3y agoTotally agree! The worst example is a paragraph that starts with ‘this’. The author might remember what ‘this’ means at the time of writing, but other readers have to then insert themselves into the author’s stream of consciousness. ‘This’ paragraphs also make no sense when extracted from the main report, or to readers who are dipping in and out
- layer8 3y agoThis is good advice.
- mike-the-mikado 3y ago'This' paragraphs are fragile to editing. Ensuring that your text is robust to updates (e.g. insertion of an extra paragraph) is good practice.
- wodenokoto 3y ago“This piece of advice”, I guess it’s good advice just don’t overdo it?
- susam 3y agoOne of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation where a team is responsible for developing and maintaining some service known by the name, say, ABC, but nobody in the team knows what ABC really expands to. In such instances, in order to avoid choosing a new name and updating all related documentation etc., the only recourse is to treat ABC as a proper noun and move on. Fictitious example: To obtain an access token for CDIS, first go to DMC at <https://dsc.prod.example.com https://dsc.prod.example.com>, click on the entry for "CDIS" on the left sidebar, click "Generate Access Token", and copy the token. What I would like to read instead: To obtain an access token for Customer Data Indexing Service (CDIS), first go to Data Management Console (DMC) at <https://dsc.prod.example.com https://dsc.prod.example.com>, click on the entry for "CDIS" on the left sidebar, click "Generate Access Token", and copy the token.
- HeavyStorm 3y agoA glossary is the most important document ANY project should have and maintain. Everything else is secondary.
- drittich 3y agoPlease explain what ANY expands to...
- lawn 3y agoNah, it doesn't pass the sniff test. Is it more important than a list of critical bugs? A document explaining how a developer can get the application up and running? A document detailing how the production server is setup and how to gain access? When you think about it, lots and lots of projects manage without any kind of glossary but would go up in flames without some kinds of documents.
- 3y ago
- wodenokoto 3y agoAll in all I think it is a good and well written guide. I’d like to add support for using passive voice in work / business emails. This is great, not only for obscuring blame, but obscuring the _opportunity_ for blame.
- cs02rm0 3y agoIs there a service for this? (Standard developer question). I found myself writing a book recently, completely left field to my normal technical work. I'm intending on approaching a literary agent but I need it reviewed first and I'm looking for dispassionate, distanced, but informed opinions.
- gghh 3y agoWell, a copy editor maybe? https://en.wikipedia.org/wiki/Copy_editing https://en.wikipedia.org/wiki/Copy_editing I've never used one, but I assume there are professionals for hire to do this. In fact I've read one of the advantage of going with a publisher (as opposed to self-publishing) is they give you an editor. But again, I'd expect a freelance market to exist.
- tomsmeding 3y ago> completely left field to my normal technical work. I'm assuming this is another baseball reference. As a non-American: what does it mean? :)
- cs02rm0 3y agoAlso a non-American (Brit). Just means something unusual. According to the 2007 Concise New Partridge Dictionary of Slang and Unconventional English, the phrase came from baseball terminology, referring to a play in which the ball is thrown from the area covered by the left fielder to either home plate or first base, surprising the runner. Variations include "out in left field" and simply "left field"
- bbx 3y agoA lot of the tips in this article are very similar to the ones provided in this fantastic book: The Elements of Style [1]. I highly recommend it, even for a non-native speaker. [1] https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X/ https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...
- gghh 3y agoIf I could add one prescription to TFA, it would be to avoid using "just" (the adverb, as in "simply") at all costs. "A monad is just a monoid in the category of endofunctors." Maybe it is, maybe it isn't, but none of that is simple. There's that math joke about proof methods, and this would be "proof by intimidation". When describing a process: "To measure the inverse reactive current in unilateral phase detractors, just use an ordinary turbo encabulator". Why "just"? Are there other methods? For what reason is this the preferred one? When giving advice: "Why don't you just use a bash script?" This implies your suggestion is simpler or more economical than my proposed approach, therefore better, but you aren't supporting its alleged superiority with arguments I can counter, only implying it.
- hansvm 3y ago> monads, "just" I think that line is usually quoting a popular joke from a comedic tour of various programming languages, and "just" is appropriate. > A monad is just a monoid in the category of endofunctors. What's the problem?
- gghh 3y agoI see. It was the first sentence that came to mind. The point I'm trying to make is, in my experience, "just" is often abused, as it conveniently relieves one from providing a sound argument.
- hansvm 3y agoTotally agreed. Your other examples were spot-on, and the general sentiment also makes sense to me.
- aorth 3y agoYes, good suggestion. I've also stopped using "just" when speaking or writing in the last few years. You can almost always drop it and retain the same meaning without sounding rude or dismissive. I've noticed this in at least one other language I'm loosely familiar with (Bulgarian) and it holds there too. When the speaker adds "просто" it has the same effect of sounding rude and dismissive.
- zoya99 3y agoHello everyone! This is my post! I'm flattered and honored that it resonated with many of you. Since I wrote that post, I followed my curiosity to become a software engineer myself. After doing that work for a few years, I've found myself missing working in a more writing-heavy role. If you're looking for an excellent technical writer, developer advocate, or another role that blends communication expertise and technical skills, let me know! You can contact me through the form on my website (https://evaparish.com/contact https://evaparish.com/contact) or via LinkedIn.
- avg_dev 3y agoI really got a lot out of the article. I think it will help my write more succinctly and clearly and to be better understood. One question: after writing the sentence “I really got a lot out of the article.”, I wondered: is this extraneous? Is this clear? Am I saying precisely what I mean? And I think, yes, I meant exactly what I said, and I went into detail in the following sentence. I am just curious what you think.
- nuancebydefault 3y agoYour first paragraph is clear, indeed the first sentence is the gist, the second explains it in more detail. The second paragraph -- the question and own answer -- seems a bit superfluous to me.
- korymath 3y agoI am not the author, and am sharing feedback because you asked with honest curiosity. Your writing is not clear to me. Using the word “really” is extraneous. Using “I think” is also extraneous; I assumed these are your thoughts. As the author notes, replace “it” with “the article”, or better yet a specific quote or idea distilled from the article. Helped “my write” should be helped “me write”. You use two -ly adverbs, which could be avoided by restructuring the sentence. You also have a list of two (succinct and clear) and then a single item (better understood). Consider breaking these two thoughts into separate sentences.
- 3y ago
- swayvil 3y agoThis is smart stuff. All of it makes good sense. I speak as a compulsive editor. You can tighten it up, and tighten it up again, and sloppy doggerel becomes so clear. Really a lovely piece of writing about writing.
- alphazard 3y agoI've heard English teachers cargo cult the passive voice thing for ever. This crowd will understand the passive voice as a form of abstraction. If anything could suffice as the subject, then it's not important to the meaning of the sentence, and you convey that in English by implying but not specifying the subject (the passive voice). In scientific procedures for example, the whole point is that anyone could replicate it. 30 grams of goop was added to the beaker. Doesn't matter if it was you or one of your coworkers, or another group trying to replicate.
- natdempk 3y agoWhen I learned about passive voice, scientific writing was often mentioned as an explicit exception. What you say makes sense when you are abstractly describing something that happened, but also I'd argue that "We added 30 grams of goop to the beaker" or "Added 30 grams of goop to the beaker" is clearer than "30 grams of goop was added to the beaker". Depends on the context and style conventions of course, but often passive voice is still poor/indirect writing in many scientific contexts.
- Scubabear68 3y agoThis post is a great set of ideas for writing. What the author is doing is constantly putting himself in the shoes of the readers, and thinking “what does the reader need here?”. Which may sound like a very tortuous way to write. But it becomes instinctual after a while. When I’m writing and don’t apply rules like this, I inevitably feel lost - and I know the reader will be too. When I end up going down a bad road like this, at some point I will throw away most or all of what I’ve written and start from a fresh perspective. I guess this would be my one addition to the author’s rules: don’t be afraid to throw away lines, paragraph, or even the whole thing if it’s not working for you.
- k__ 3y agoI needed the repetition tip the most. I always feel like repeating myself makes the text unwieldy and then clutter it with "this". Grammarly always complains, "What is this refering to?" Well, obviously a concept of the previous sentence! I will repeat myself more often and then rephrase the repetition.
- BossingAround 3y agoHonestly, I would recommend never using "this" or "that" - it often makes sense only after you force the reader to re-read the sentence.
- BossingAround 3y agoI would add eliminating future tense. There's very few times when future tense is actually required. It's one of my pet peeves when docs say something like "Click X. This will open a prompt ..." when it can say "Click x. This opens a prompt ..."
- euroderf 3y agoYes. The user is living (i.e. working) in the moment, and so should your text.
- Karellen 3y ago> Who are you writing for? This is the hardest part of writing for me, especially blog posts. I can never decide if I'm writing for a) highly technical readers who know 95% of the concepts my idea is based on, and I just want to connect the concepts together in a way the they might not have thought of, b) generally technical readers who have a grasp of the concepts my idea is based on, but will need some details to tie them into the idea I'm building on top, or c) readers who are not-especially-technical in the field, who might be nevertheless be interested in how a few things works, and my idea too. I feel like part of it is that I am all these readers, depending on the subject. I enjoy reading articles about the areas of software dev I'm deeply interested in, but also about the odd idiosyncrasies of software that is used in fields I don't normally cover, but I also enjoy reading articles about e.g. the challenges involved in developing geothermal drilling systems, or elevator systems in 80+ story buildings, despite having very little experience in either. I keep going through cycles of "If I just explain this part in a bit more detail, the post will be accessible to an order of magnitude more readers" to "this is way too long, I should cut some explanations, or add footnotes, or more wikipedia links" to "I'm assuming way too much previous knowledge here, or asking the reader to do too much extra work to follow my point".
- VladTheImpalor 3y agoGood question, and one I'd like to see discussed more too. From my point of you, your point "a)" is the one I never choose. In my opinion, one could rarely write something for that audience which might be novel to them. Perhaps I'm just not that smart, but to me, when I picture the true masters in my field, I rarely need to communicate anything to them that they haven't figured out for themselves already, and in the rare case that I might, those types of people don't mind a bit of revisiting of the fundamentals anyway. My favourite type of writing is one that also comes in handy to myself a couple of years down the line, which inevitably involves a modicum of handholding and starting from some fundamentals. So I'd say most of the articles should be b) or c).
- kens 3y agoYeah, I find picking the audience difficult too. For my blog posts, I want to include the details for specialized readers, but also make the post accessible to the generally technical readers (roughly the HN crowd). (If I wanted to write for only the first group, I'd write academic papers.) My solutions are to add enough background for someone who isn't an expert (even if it seems repetitive), and to use extensive footnotes for information that most people won't care about. Also, I try to put topics into a broader framework: a few paragraphs on history and why the topic is important. A narrative framework helps too, so even if someone doesn't follow all the details, they get a sense of going on a path e.g. from problem to solution. I also try to break up massive chunks of text with photos or diagrams but worry that I lean on this too heavily. When I read popular books on scientific topics, I try to study the techniques that they use. For example, "An immense world" is crammed full of interesting facts and stories, keeping the book even though it is discussing technical concepts of sensory perception. "Immune" describes the immune system in detail, making heavy use of metaphors and imagery and repeating these throughout the book. Other books focus on the people, moving the technical details into the background. I'm no expert on this, of course. People seem to like my blog posts, though, so I figured I'd share my thoughts.
- quaddo 3y agoBack around 20 years ago I was with an MSP. We depended heavily on having a well written - as current as possible - prod guide for all operations. At some point it occurred to me that there was likely a way to draw upon the experiences of those who came before us. In my case, it seemed fitting to use newspapers as a reference. Somewhere I’d come across a concise guideline, a list of do’s and don’ts. The only thing I clearly recall now is keeping the key info “above the fold”, which is likely something that might puzzle someone who has never handled a newspaper. Even so, the concept is easy to share and grasp. I wish I’d kept that list. I’ve tried looking for it within the past couple years, to no avail.
- roryokane 3y agoWhat is an MSP?
- ARandomerDude 3y ago> Don’t use adverbs > There is nothing inherently wrong with adverbs. They are just part of a category of things that I believe are lazy in writing. Comparing this quote to the rest of the article, it appears the italics convey vocal emphasis. I find it somewhat ironic that “inherently” is an adverb.
- tapanjk 3y ago> You might think it’s obvious what an acronym means, but a new reader may not. The other scenario is when the reader is not new, but it is too late to ask.
- keybored 3y agoToo much emphasis/use of bold, overuse of actual/actually.
- prerok 3y agoThank you for the write-up! I did not know I have been erroneously omitting commas in English. In Slovenian, my native language, commas always delimit clauses in a sentence. We got that from German, which got it from Latin. I still don't understand why English chose to omit commas in some cases. It just confuses the reader of larger sentences. In some fiction books the omission made some sentences completely unreadable. Granted, it was the author's fault but still... Why?
- penguin_booze 3y ago> Who are you writing for? And editor should know they should use 'whom'.
- askhan 3y agoNice list. I have however one picky pique within the Split it Up recommendation: > Example: If you’re looking for me I’ll be in my office. > Revision: If you’re looking for me, I’ll be in my office. > Example: Due to the fog our flight was delayed. > Revision: Due to the fog, our flight was delayed. If the sentence is unambiguous without the comma then lean towards omitting it. Especially with the second example, with the clause being only four syllables long, the comma slows down the reader so much that the music of the sentence is broken. "Fog our flight" cannot be misinterpreted — nobody thinks of fogging a flight. Indeed the lack of a comma foretells to the reader they can confidently plow ahead through a well-tended sentence. Also on the topic, Larry McEnerney's 2014 video "The Craft of Writing Effectively" https://www.youtube.com/watch?v=vtIzMaLkCaM https://www.youtube.com/watch?v=vtIzMaLkCaM (100m). He was Director of the University of Chicago's Writing Program.