Hacker News new | past | comments | ask | show | jobs | submit login
Shell scripts to improve your writing, or "My advisor rewrote himself in bash." (might.net)
143 points by mbrubeck on July 19, 2010 | hide | past | web | favorite | 31 comments



There's no problem with having a house style, of course, but it's obnoxious to claim that following one particular stylebook makes one a "better writer". Particularly obnoxious in the linked article are the claims that "the removal of all adverbs from any technical writing will be a net positive," and likewise for "the removal of the passive voice".

Adverbs are indispensable to good writing, technical or otherwise. Notwithstanding the claims of a variety of self-proclaimed experts, no good writer will omit adverbs, and no writer can successfully omit all adverbs without at the very least sounding incredibly choppy and awkward. The author of the linked article included quite a few; even just counting those adverbs that end in "-ly", I found ten (fortunately mechanically really genuinely personally frequently unfortunately solely rightfully technically), and there was even an adverb ("so") right there in the sentence where he was condemning adverbs!

As for the passive, the author acknowledges the difficulty of avoiding them, but claims that their removal is still an improvement, though without explaining why. In fact, it makes the writing seem rather choppy (as if the author had to spend too much time paralysed by a set of rules to follow to actually be able to make the text flow). And despite apparently putting in a great deal of effort to avoid them, the author still included at least two that I found in a quick reread: "drawn for them" in the "beholder words" section, and "accepted for publication" right at the bottom. In both cases, the result is perfectly readable, not at all fuzzy, and entirely unremarkable---which shoots a rather gaping hole in the argument that there is anything wrong with a passive voice.

I feel sorry for his grad students, and only hope that when they come out the other end, they will sensibly discard the silly mandates of their advisor, rather than perpetuating the myths....


All writing rules have exceptions. But in my experience as a CS grad student, his guidelines are good. His guidelines tend towards less words and more precision. Those are good goals.

Also, having seen Matt Might give a talk on a day's notice when he was still a grad student, I think his students are in good hands.


My goal with these scripts is really to prevent inappropriate use of the constructs I described. Reading the article over again, I do see how it makes it seems like I'm on a quest to ban these constructs. That's my fault for not being clearer. ;)

Most of the time, my students use these constructs without thinking about it. That's the real problem.

Perhaps I should have posted a few paragraphs from a recent draft to highlight what I meant by inappropriate (or excessive) use, but I don't think my grad students would appreciate a public shaming.

As I mentioned in the article, there are times when the passive voice and adverbs have their uses.

It would be a net positive if my grad students removed all their adverbs and all passive voice from their recent drafts.

(Of course, the optimum would be to leave only the appropriate uses of these constructs.)

I'm willing to bet this is true for a lot of new grad students in science or engineering first learning how to do scientific writing.

It was certainly true for me once upon a time.

Having the scripts highlight these constructs forces students to ask the question, "Is there a way I can say this better?"

If the answer really is "No," then they can leave it in.

But, I want them to think about it.

/article author


> If the answer really is "No," then they can leave it in.

Ah! That bothers me a lot less, then; I still wonder about some of the choices, and I think you underestimate the utility of adverbs and passives, but if you were stating style preferences rather than rules, that seems fine.

Unfortunately, the linked post as written still appears to propagate the dumb Elements of Style canards as if they were absolute rules. :P


For experimental contrast:

I have no problem with a house style, but the claim that following one particular stylebook makes one a "better writer" annoy me. Worse, the linked article claims that "the elision of all adverbs from any technical writing," and "the removal of the passive voice," "constitute a net positive."

Good writing, technical or otherwise, requires adverbs. Notwithstanding the claims of a variety of self-proclaimed experts, no good writer will omit adverbs, and no writer can successfully omit all adverbs without sounding incredibly choppy and awkward. The author of the linked article included a few; counting those adverbs that end in "-ly," I found ten (fortunately mechanically really genuinely personally frequently unfortunately solely rightfully technically), and in the sentence condemning adverbs he included an adverb ("so").

As for the passive, the author acknowledges the difficulty of avoiding them, but claims that their removal still improves writing, though without explaining why. In fact, it makes the writing seem rather choppy (as if the author had to spend too much time paralysed by a set of rules to follow and had none left to make the text flow). And despite putting in a great deal of effort to avoid them, the author still included two or more that I found in a quick reread: "drawn for them" in the "beholder words" section, and "accepted for publication" at the bottom. In both cases, I find the result perfectly readable, not at all fuzzy, and entirely unremarkable--which shoots a rather gaping hole in the argument against the passive voice.

I feel sorry for his grad students, and hope that when they come out the other end, they discard the silly mandates of their advisor, rather than perpetuating the myths....


I'm not sure exactly what you're attempting here, but you made a lot of changes to text involving neither adverbs nor passives, and you missed several adverbs. What was this trying to experimentally prove, exactly?


I'm a fan of show, don't tell.

Brilliant.


I fear you're confusing good writers with computer science graduate students.


Usually the rule is "no -ly adverbs" - so perhaps he should have been more explicit. The author's point, though, is that doing so makes for better, clearer writing and that in nine cases in 10, it is the better option.

Regarding the passive voice, the author is just providing general clues to good writing and is not imposing a dogma. Certainly the passive voice makes for a boring read.

So I think that his point is: get rid of adverbs for clarity, and change the passive voice to an active one to maintain interest.

I must say I agree.


> Usually the rule is "no -ly adverbs"

What?? That makes even less sense than the "no adverbs" rule. Nothing in the syntax or semantics distinguish -ly adverbs from any other. (I only included -ly adverbs in my count because I was lazy and they were easier to search for.)

> Certainly the passive voice makes for a boring read.

You don't read much that isn't boring, then, eh? Too bad. Good writers use the passive voice. Writing that avoids the passive voice is not good writing.


You're right about one thing: there is not much good writing out there. The -ly rule is a pretty established one. These adverbs are almost always pointless. Other adverbs (for example "not" or "almost" or many of the adverb phrases) are more crucial to language and important for clarity.


My style checker finds weasel words, passive voice, and repeated words (a lexical illusion). It also finds confused words as well (another lexical illusion). It's not integrated with LaTeX but it is available for Firefox, Google Chrome, and OpenOffice.org.

http://www.afterthedeadline.com


I just deleted my half written comment about afterthedeadline, I use it a lot to do exactly as the post describes. It catches my mistakes every time, eventually I will stop making them heres hoping.

Thanks for it though, great tool.


>and repeated words

One of the things I hate most about English (and this is by no means a rant on how stoopid English is) is that "that that" can be grammatically correct. It's a minor thing really, but I could swear it's mocking me some days.


Check out the "Lexical ambiguity" section of http://en.wikipedia.org/wiki/List_of_linguistic_example_sent...


haha, nice, hadn't seen that one before. I love the last Japanese one (chosen because I've had some Japanese)

  Touou wo ooou. (東欧を覆おう。) meaning "Let's cover eastern Europe."


That that that that offers a nice example too.


That "that that that that" that that comment included would only be correct if you included quotation marks.


The first draft had had "had had".


detex is easy to use and strips the latex out of latex files. You can also extract the text from a dvi using catdvi, and from a pdf using pdftotext, so I think you could probably afford to support latex :-)


The passive gets a bad rap a lot of the time, but getting rid of passives isn't always the best way to go about things. An approach which forbids all passive verbs often results in less readable or less appropriate prose, because there are honestly places where the passive is the correct thing to use. Broadly speaking, it's better to educate yourself about those situations than to treat it as wholly bad and eliminate it entirely.

I'd go into more detail, but Language Log has discussed it in great depth: http://www.google.com/search?q=site:http://languagelog.ldc.u...


there are two gnu utilites that are useful for writing: gnu style and gnu diction. http://www.gnu.org/software/diction/diction.html

diction finds common mistakes. style gives some metrics (may or may not be useful, YMMV).

they have a similar theme as this article.


My doctoral supervisor also taught me to write and it was very, very valuable. It enabled me to write for newspapers later and write my book. Learning to write is important because it helps you to see the subject you are writing about clearly.

In ReWork, the 37 Signals' guys mention that if they have the choice between two potential hires of equal ability, they'll choose the one who's a better writer.


Sure they do - but that isn't really surprising; why not take the better writer? It might be useful, can't hurt and there is no downside.

The really interesting thing is _how_ much they are willing to compromise; would they prefer a mediocre programmer with flair for writing? If not, it is just meaningless platitudes.


Prose and programing aren't as unrelated as they might seem. Ultimately, both are exercises in using a particular set of grammar and syntax to convey intent.


>if they have the choice between two potential hires of equal ability, they'll choose the one who's a better writer

There's a modifier missing in "equal ability" to make that sentence logical. Writing is an ability itself.


I don't think that deserved to be downvoted, but I think that it implies "all other things being equal".


All other things being equal, I'll take the candidate who's better at pinball.


Isn't that sort of a given, though? If two people are otherwise equal, and one is better at something that will contribute even the smallest gain to your business, why wouldn't you choose him? There can be no other criteria, as they are otherwise equal.


Jesus, the advice is perfectly clear. It doesn't require logical dissection.

    If you are unable to choose between two candidates, pick the candidate
    who is a better writer (as opposed to a better lumberjack).
It assumes that your original method of choosing did not take into account writing proficiency, and that one candidate is a better writer than the other.


I realize it's clear. I just don't feel like it contains much "advice." It's basically saying pick the better candidate. Duh?




Registration is open for Startup School 2019. Classes start July 22nd.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact

Search: