# Writing style guide * **Never use naked pronouns** — that is, don’t use “they” or “it” in a sentence without first using the noun you’re referring to. It might be obvious to you the writer what you’re referring to from a previous sentence but it’s often confusing for a reader. Yes, it might seem a little repetitive. * Bad: “This in turn leads to …” * Good: “This state of play in turn leads to…” * **The passive voice should be minimized.** (Pun intended). Often, people use the passive voice in ‘procedural’ situations, especially if they have scientific training. The (reasonable) intention is to focus on the experiment, not the experimenter. But this can be achieved by assigning inanimate parts of the experiment a tad of agency, in the manner of “The chemical reaction requires these two compounds to be mixed …” ; “the next step involves…” * **Don’t bury the lede**: Say “X would do Y by doing Z”, not “By doing Z, X would do Y.” One exception might be if it immediately comes after a sentence describing Z. * **Never say ‘I think’**: it’s unnecessary throat clearing. You’re the author — anything you say that is not a hard fact of the world is implicitly your opinion unless you state otherwise. * **Asides, caveats, and parenthetical go after the main idea**. When you’re writing, the main idea is in your head so it makes sense to do the parenthetical. The reader has *no idea* what the main idea is going to be on the other hand. (I wanted to write the previous sentence starting with “on the other hand”…) * **Do not split up ideas**. This can happen both within sentences and between them. * An example of splitting up an idea within a sentence: “The horse, note that horses can run at 25 miles per hour, was important for mongols.” * A (not particularly good — need to find a better one) example of splitting up ideas across sentences “Scythians ride horses, which can move up to 25 miles per hour, on campaign which allows them to move incredibly quickly and defeat heavily armored foes. Herodotus introduced the term Scythians for the people of the step.” This can be particularly bad in a scientific context where you talk about a term-of-art in one sentence but don’t define it until the next sentence. * ==This is Ben’s particular thing== Single quotes are for situations where you would want to make air quotes around a word. Double quotes are for actual quotations from another person. * A list of redundant combinations of words to avoid: * “Could potentially” * Break out lists into numbered lists or bullet points instead of embedding them in a paragraph. When you are writing and publishing digitally space is free. * Say the thing first, and then the justification. The above point is tempting to write in the reverse order but it makes it harder to read. - When you’re writing about ideas and you are not writing for a community with very specific demands, write in the Academish voice ([[vanhardenbergAcademishVoice2023]]) - Do not use academic jargon [[Forbidden Academic Jargon]] - Avoid using the term “humans” to refer to humanity — it makes you sound like a robot/something separate from humanity. Other options include: “mankind” “Humanity” “people” - Minimize the use of qualifiers like “should” “would” “might” “arguably” - Written lists are maximally aesthetically pleasing with three elements. (Corollary, if a list needs to have more than three elements create a bulleted list) (h/t [[Santi Ruiz]] ### Specifically for business or technical writing that’s designed to maximize information transfer - Default to using less than 30 words per sentence unless there is a very clear reason not to. - Replace adjectives with data - More generally, avoid using adjectives and adverbs - Explain technical terms, acronyms and abbreviations the first time they appear ### Related - [[Jerry Neumann]]’s [Writing Guide for Business](https://docs.google.com/document/d/1PqbdAnYM79tLvO3yWCt2QH2T1HuQ58poNUsM7QzuE-c/edit) - https://www.americanscientist.org/blog/the-long-view/the-science-of-scientific-writing is an amazing short article on technical/business writing. - If you can find it and have the time [Sense of Structure, The: Writing from the Reader's Perspective](https://www.amazon.com/Sense-Structure-Writing-Readers-Perspective/dp/0205296327) expands on the above and is awesome. - Obviously [Strunk and White](https://en.wikipedia.org/wiki/The_Elements_of_Style) is the OG here.