18 ms·
My PhD advisor rewrote himself in bash (2010)
- nonrandomstring 2y agoUseful for those who, for some unfathomable reason, don't use emacs. Might be hard to get into a good workflow as running them and then re-editing seems tedious. Author gives credit to emacs "writegood", but my all-time fave style-nazi plugin is "artbollocks-mode".
- 0xbadcafebee 2y agoPut "AI" in the name and sell it for $5M?
- tetris11 2y agoduplicate words: sed -z -r 's|(\b[^ ]+\b)(\1)+|~Dupe!\1~|g'
- mooreds 2y agoIf you are looking for more of this, check out vale.sh. It lets you add all kinds of style guidelines, including avoiding weasel words. Here's the GH action we use to run vale on our website at PR time: https://github.com/FusionAuth/fusionauth-site/blob/main/.github/workflows/vale.yml https://github.com/FusionAuth/fusionauth-site/blob/main/.git... and our config: https://github.com/FusionAuth/fusionauth-site/tree/main/config/vale/styles https://github.com/FusionAuth/fusionauth-site/tree/main/conf... We've found it helpful to enforce style but probably aren't using it to the full extent.
- codazoda 2y agoVale.sh looks pretty good, thanks for the reference. I’m currently editing the third edition of my book and a bunch of articles for my website. This will come in handy.
- barrettondricka 2y agoI use a version of these scripts all the time. though all-in-one spell-checkers like vale.sh are more convenient.
- morpheuskafka 2y ago> I'd even go so far as to say that the removal of all adverbs from any technical writing would be a net positive . . . > Bad: We offer a completely different formulation of CFA. > Better: We offer a different formulation of CFA. Getting rid of all adverbs (e.g. "vigorously stir the solution," "monotonically increasing function," "spontaneously combustible") hardly seems wise, whether technical writing or not.
- zem 2y agoeven "completely different formulation" could convey something different from "different formulation", e.g. "we tweaked the method" vs "we scrapped the method and started anew". I also disagree about the "beholder words"; to me "it was surprisingly low" means "I am drawing your attention to the fact that the low value surprised me" rather than "you need to be surprised by the low value".
- warkdarrior 2y agoDon't tell the reader how to feel, but rather guide them to feel that way through your ideas, results, and conclusions.
- akdor1154 2y agoHis point isn't to ban surprisingly, it's to prefer 'we the authors were surprised it was low' over 'you the reader should find it surprisingly low'.
- zem 2y agothat's my point; to me "the results were surprisingly low" does mean "we the authors were surprised it was low", and reads better than "to our surprise the results were low". my reasoning is that the former is more of a parenthetical, as much as to say "the results were low (and it surprised us)", rather than putting the "us" who were surprised front and centre and making the low results subordinate to that.
- dogmayor 2y ago
- dang 2y agoRelated: Shell scripts to improve your writing - https://news.ycombinator.com/item?id=13295530 https://news.ycombinator.com/item?id=13295530 - Jan 2017 (55 comments) Shell scripts to improve your writing, or "My advisor rewrote himself in bash." - https://news.ycombinator.com/item?id=1529166 https://news.ycombinator.com/item?id=1529166 - July 2010 (31 comments)
- emmelaich 2y agodiction and style commands were present in early Unix, which did similar jobs. You can get them (or versions of them) from GNU. They're in homebrew. https://www.gnu.org/software/diction/ https://www.gnu.org/software/diction/ From what I remember, they weren't great; this bunch of programs probably does just as well.
- deleted 2y ago[deleted]
- dogboat 2y agoSee also https://vale.sh https://vale.sh
- Gimpei 2y agoIn my field, writing quality was on the very lowest rung of importance, below even teaching evaluations. As much as I value clear, concise prose, I’d say a grad student would be better served working on public speaking especially when faced with hostile questioning, and, sadly, with brown-nosing. Yes I am bitter :p
- disconcision 2y agohow can you tell? likely this is field-dependent but even if because reviewers dont tend to comment on writing quality it doesnt mean it doesnt play a factor in acceptance. if you annoy people, (sometimes even especially) in ways that dont feel substantive enough to merit mentioning in a review, it can make them more inclined to be critical about aspects they might otherwise gloss over. (i acknowledge this is unsatisfyingly unfalsifiable, and that it can also go the other way, in that selectively bad writing can be used to attempt to paper over holes)
- kjkjadksj 2y agoI think even more than public speaking is just seeking a therapist. People get in over their head but its by their own doing. The stakes are never as high as you have built them up in your head. People want you to pass.
- ergotux 2y agoTwo resources which helped me improving my writing, when I was writing my thesis were "How to Write Mathematics" by Paul R. Halmos and "Mathematical Writing" by Donald E. Knuth et al. I would always start with Halmos to get into the spirit of perusing clear and precise communication. The "Bad/Better/OK" suggestions especially reminded me of the discussions in the lecture notes from Knuth et al. And at a third step a linter such as the proposed one is probably helpful, if something slips through. I think these resources are essential for anyone who writes on any subject which at least involves definitions here and there.
- BOOSTERHIDROGEN 2y ago[flagged]
- Out_of_Characte 2y ago[flagged]
- knighthack 2y agoThat doesn't seem like a very divisive statement.
- cm2187 2y agoNext: create a bash script to find out if the PhD advisor reads HN
- kjkjadksj 2y agoWouldnt need a bash script, phd advisor probablu gave you the password to everything already. Use the code they gave you into their office. Log into that laptop on their desk and use the gui to parse the history and see for yourself. If they catch you they probably wouldn’t even care.
- bsder 2y agoMy first reaction was "This person isn't in a hard science like physics or engineering. Maybe medicine?" Ayup--medicine. Style can be annoying but lack of context is deadly. "To our surprise, false positives were low (3%)." is not much of an improvement. "To our surprise, false positives were low (3%) as we expected closer to 10%." IS an improvement. However, that statement in a hard science is going to cause people to start asking some questions: Is 3% actually low? Why was the expectation so high to start? Did you screw up your error bars? Is it really 3%? etc. "It is difficult to find untainted samples." Because is missing. In addition, this comment is rarely germane. I, the reader, don't really care. That's your problem. Either find the samples to get to statistical power or get a different method. As the reader, I only care if you did something weird in order to sidestep the problem--that I want to know about. All of the recommended things still retain "weaseliness" while trying to sound like they don't. Finally, I would love to have his problem of merely cleaning up some weasel words when most students I know (even at the PhD level) still have trouble stringing together coherent arguments and understanding where the holes and weaknesses are.
- rsfern 2y agoFYI, the author used to be a programming languages theory researcher before changing fields to biomedicine. So I think you’re reading into the field a bit You last point definitely resonates though
- bsder 2y agoCS doesn't really classify as a "hard science" either, to be fair. All my physics professors, for example, were anal retentive about error bars--you had to put your error estimates in the notebook in ink before you took measurements. If something was "better than expected" you were about to have a painful journey figuring out why.
- liontwist 2y ago> To market a paper, the author must make a compelling case for why her idea deserves access to that resource. In other words, journals are filled with papers that were sold the best, not the most important ideas. And as the author also says, superficial things like hard to detect typos are often a deciding factor because the reviewers can detect them. we should stop pretending there is objectivity and embrace journals that reflect taste and opinion of the editor. Or have standard places like arxiv for publishing everything. There is no scarce resource for uploading pdfs.
- kjkjadksj 2y agoThe editor is not the one making the call really. Its the reviewers. If they give it few marks or no marks then that’s it, its published. If they dog that paper down then the editor has to sit up in their chair and actually decide whether or not the authors made sufficient change to address the reviewers complaints. But even then its still the reviewers who are demanding the standard, not the editors.
- aeonik 2y agoWhile we're at, improve the citation system, so I the references become hyperlinks, and code artifacts can be accessed.
- quickgist 2y agoI find myself disagreeing with many of the examples. E.g. according to the article: Bad: It is quite difficult to find untainted samples. Better: It is difficult to find untainted samples. Bad: We used various methods to isolate four samples. Better: We isolated four samples. Something being quite difficult reads significantly differently than just being difficult. You haven't made the sentence better, you've changed the meaning. And the fact that you used various methods instead of a single method is information missing from the second sentence.
- t8sr 2y agoAnd this is why I now have to read 30 page design docs that could have been 3 pages and said the same thing. Please try to understand why people have such strong dislike of floral writing, especially in technical texts. If you read a lot of papers or designs, it makes your life miserable.
- perching_aix 2y agoWhen it comes to technical writing the only thing I can really discuss is documentation, and the key thing I'm personally looking for there is structure. It could be about basically anything, just please, pretty please, for the love of god, make it structured. And I don't mean sections with catchy headings, I mean as structured and reference-like as possible. I want to minimize the amount of time I spend reading prose and searching around, as well as the chance of missing things. I want to hit CTRL+F and be put where I need to be stat and have that be enough. Structure alone can convey a lot of the idea behind how something works - please trust me to able to utilize it to make basic leaps in logic. A bad example for this is AWS documentation. It's a mish-mash of prose and structured reference. A good example is the AWS CLI documentation (although if they lead with example usages first, that'd be even better).
- deleted 2y ago[deleted]
- maccard 2y agoWriting good technical text is an art. There is a certain amount of fluff that helps, and it’s almost unnoticeable when it’s there. Without it, it’s too terse. Quite often, my complaint of technical documentation is “it did exactly what the docs said it would do, except in a situation that I didn’t expect it to do that”.
- gmac 2y agoCan confirm the value of checking for repeated words such as ‘the the’. This is the final example I give my Econ PhD students in a session on RegExps: https://users.sussex.ac.uk/~gm268/iphd/regexps/regexps.pdf https://users.sussex.ac.uk/~gm268/iphd/regexps/regexps.pdf
- skalarproduktr 2y agoThis is a great summary how to use regexps, complete with some very nice examples. Thank you!
- ninalanyon 2y agoJust so long as it doesn't blindly modify "that that".
- gmac 2y agoRight. You can just search for /\b(\w+) \1\b/ and see what comes up. There are usually false positives of one kind or another.
- Timwi 2y agoI once wrote a sentence with a double “in” in it — it was something like “let's see what state this is in in two weeks’ time” or similar — and at least two people commented thinking that it was wrong and needed an “in” removed...
- ofalkaed 2y agoAs a humanities sort I appreciate this but the scripts sort of go against the general thrust of the text since the scripts can not understand context or semantics, it feels like they would push many towards blindly following prescription instead of what he is advocating for. I think elaboration would have served better than bad, better and good examples which do not explain the issues and assume the reader will intuitively understand. We get some elaboration but not enough. Gardner's Modern English Grammar should also be the primary recommendation for further reading, Gardner has a gift for explaining the nuances of these things. Style guides are guides for the style of a given publication or writing within a discipline, not guides on writing well or with style.
- jimbokun 2y agoYes, I think the tool should highlight usages to double check, not blindly apply changes and submit.
- burgerzavr 2y ago[flagged]
- anonymousDan 2y agoI found this an interesting read: https://www.cambridge.org/us/universitypress/readers-brain https://www.cambridge.org/us/universitypress/readers-brain It gives a neuroscience perspective on what makes certain writing styles clearer.
- teekert 2y agoThis what Claude/Chat do when you ask them to make text more concise. Have to say, Chat does produce what I am looking for in one go more often. Claude always makes lists or makes things way to concise. Maybe I need other prompts.
- tgraf_80 2y agoGood intentions, indeed. Creating lots of steering committee slides, I know about the wish from the audience of a simpler language. But ‘very close’ is different from ‘close’. It’s not just salt and pepper but trying to articulate a complex and nuanced reality. And yes, research papers then sound a bit less solid and complete- sorry, but often this is the reality you should not hide.
- jimbokun 2y ago> But ‘very close’ is different from ‘close’. What's the difference?
- deleted 2y ago[deleted]
- tgraf_80 2y agoit's a way to express steps in a continuum (given by the context): - not close (1) - close (2) - very close (3) - arrived (4) That's how language works. It's not mathematics and uses "salt and pepper" to convey the message as accurately as possible.
- simonw 2y agoI got Claude to port those Bash scripts to a web UI so I could paste code directly into it and see what came out: https://tools.simonwillison.net/writing-style https://tools.simonwillison.net/writing-style Claude transcript here: https://gist.github.com/simonw/e9902ed1cbda30f90db8d0d22caa06d2 https://gist.github.com/simonw/e9902ed1cbda30f90db8d0d22caa0...
- bmacho 2y agoI don't think it is working properly. The second(?) pattern match is bad. For example, for It is quite difficult to find untainted samples. We used various methods to isolate four samples. it gives Found "quite" in: "is quite difficult to find untainted samples." Found "various" in: "" Otherwise great work, I like these very fast html/js tools.
- KTibow 2y agoLooking at the code, the issue is that both `findWeaselWords` and `getContext` construct a list of words but do it differently: const words = text.toLowerCase().split(/\b/) vs const words = text.split(/\s+/)
- simonw 2y agoI pasted these two comments into Claude and had it update the tool: https://gist.github.com/simonw/dc79f6adcdb189469890bc0a44331774 https://gist.github.com/simonw/dc79f6adcdb189469890bc0a44331... New version is now live at https://tools.simonwillison.net/writing-style https://tools.simonwillison.net/writing-style
- DonHopkins 2y agoWhy not just use Claude itself to review the writing, instead of having it write a much less capable and brittle and limited bash script to do it? You could even ask Claude to write a prompt for itself that performs the same or better function than the bash script. Bash and Perl are like duct tape and chewing gum, so terrible for that kind of stuff, and it's just what Claude does best. It can go so much further by actually weighing alternatives and suggesting changes, instead of just flagging problems. And no weird regular expression inconsistencies that cause false positives and negatives and parsing errors.
- nazka 2y agoIf anybody likes this article and wants to know more about the process of writing effective PhD papers they should watch [1]. In fact, anybody who desires to improve their communication skills should watch it. It is so good that I would have paid to have access to this video! [1] https://youtu.be/vtIzMaLkCaM https://youtu.be/vtIzMaLkCaM
- lupire 2y agoThe script appears to be missing a check for "long series of single-sentencr paragraphs", which quite harms readability.
- 65 2y agoI'd even go so far as to say that the removal of all adverbs from any technical writing would be a net positive for my newest graduate students. I've heard this before. Stephen King hates adverbs. However, it can be very difficult to remove all adverbs from your writing. "randomly" for example is an adverb, and if your sentence uses it, it can be difficult to rewrite the sentence without "randomly" that isn't long and complicated. Many adverbs are emphasis words that don't need to be in the sentence ("extremely" for example), but other adverbs are critical to the sentence.
- saghm 2y agoI only heard the recommendation to completely avoid adverbs for the first time the other day, although in the context of creative writing rather than technical. I think there's validity to trying to define a uniform style without fluff for technical writing, but I can't help but think that trying to studiously follow personal stylistic decisions of famous try to improve as a writer won't usually end up with something particularly original. Does anyone think that Stephen King got where he is today by just blindly following idiosyncrasies from writers who came before him rather than developing his own style?
- 65 2y agoFunny thing is, he doesn't even follow his own advice. Many of his books include lots and lots of adverbs (The Shining, for example). Besides, adverbs make writing more emotional. Would you rather read the sentence "I'm extremely thirsty" or "I'm thirsty" - the former has more punch and describes the state of thirst better. Try re-writing that sentence describing extreme thirst levels without adverbs, you start getting into an overly technical, hard to read writing style. "My thirst is extreme" (a sentence which doesn't describe the feeling of being thirsty) or "I am in a state of extreme levels of thirst" (a sentence that sounds too technical). The advice should be "don't use so many adverbs," not "don't use adverbs at all." Adverbs exist for a reason.