Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

gnat (29)

gnat
  (email not shown publicly)

Journal of gnat (29)

Wednesday September 25, 2002
05:23 PM

Be a better writer

[ #8014 ]
  1. Run your own spellcheck, don't make me do it for you.
  2. Learn its vs it's.
  3. Don't use the future tense unless you absolutely have to. "When you run this program it will delete your files" is better written "Run this program to delete your files" or "This program deletes your files" or any of a zillion other similar ways.
  4. Try to find the shortest way to say something. Try so I don't have to. Please. At least avoid bullshit deletable phrases like "the kind of thing" and twaddle like "is the reason for" (usually a longwinded way to say "because").

I'm sure there's more, but this is a good way to start (no, Dan, you didn't prompt this :-).

--Nat

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Here's another one:

    Avoid passive sentences. Make your verbs active! Don't be afraid to let the subject of your sentence take action, even if in reality (whatever that is) it's an inert object.

    Example: Instead of "That book was blowing my mind," try "That book blew my mind!"

  • I made an effort to remember the difference between its and it's while working on the Masons book, because I didn't want to look like a _total_ moron to the editor/copy editor/etc.

    I've never really been able to keep track of the difference before, and I'm sure I'll forget soon, but I think I did a pretty good job while actually writing the book.
  • I detest the word "utilize" in nearly all situations. I nearly always prefer "method" to "methodology", unless you're talking about studying methods. I also use too many adverbs. Long sentences usually suck.

    That'll do -- for about five minutes. GRR!

    • use v utilize is one of mine, too. In fact, you're guaranteed to get my asshole crawling up my spine to garrotte my brain if you write was utilized by. Yay, clumsy construction and a bullshit word!

      Editing has a lot of aspects, but the one I'm doing a lot of now is rearranging words and sentences so that the point can come through. I'm always amazed at how easy it is to hide the purpose of a paragraph through clunky construction.

      --Nat

  • Is is just me, or are there vast seas of difference between its/it's confusion and arbitrary latin-derived strictures about future tense and passive voice? The former is just a spelling error, and one way (whichever one its;) is misspelled. The latter are violations of rules that help with formal writing, but are rarely heard of otherwise, and are routinely violated in speech. The guy on the street has no idea what you're talking about (or no idea of what about which you are talking?) -- although he prob
    • Almost every "rule" is violated in spoken language (and anyway, who can hear the difference between "its" and "it's"? :-).

      That's okay for most people (less okay for professional orators such as politicians, not that I'm thinking of a particular jackass with his finger on the nukular button). In case it wasn't clear, I was talking about writing that I have to edit for publication.

      When you're writing, you have only the words to communicate with. And printed words are a very clumsy way to communicate (th

      • I guess I don't understand mistaking its for it's, because once you unpack it, the mistake's right there -- "X rain" is either "it is rain" (it's) or "the rain belonging to it" (its). So while it may be easy to misspell, there's a straightforward way to bring language intuitions to bear on the problem. Plus, I thought it was "good style" to avoid contractions in formal writing. Maybe this is why...

        On the other hand, if asked whether I should say "the book which I like" or "the book that I like", it's d

        • "which" tends to be more often right in English than in American English. I wonder how an editor penalises us brits ;-)
          • Perhaps in spoken English, but in written English the rule is the same for every culture. That helps you identify something, whereas which gives you more information. Consider ...

            Matt kicked the dog that barked.

            There may have been several dogs. One barked. Matt kicked it.

            Compare that to this ...

            Matt kicked the dog, which barked.

            There was one dog. Matt kicked it. It then barked.

            Gwammaticians call the former a defining or restricting clause, whereas the latter is a non-restrictive. The non-

        • Um... in the 'that'/'which' example you give, what's wrong with "the book I like"?

          I always get mixed up with shall and will. But I gather the US rule on that is 'You shall always use will.'

        • if you know of one, please let us know!

          Here's the rule I always use: I recite to myself, "Dogs which bite" and "Dogs that bite". Nat's right about the comma, as in the first example I'd rather have "Dogs, which bite." That's the way it flows for me (punctuation-foo).

          Anyway, when I recite these two phrases, I hear their meaning. The first implies that "all dogs bite," and I'm talking about all dogs, while the latter implies that "some doges bite," and I'm just talking about those particular dogs. Then

      • ++ on everything you said about the importance of correct writing.

        I come from the same state as President Bush. I remember my fifth grade teacher, Ms. Tanner, teaching us to say "nuclear," not "nucular." She had everyone in the class, even some particularly ditzy girls, say it properly. It has stayed with me since then. [Although I remember in sixth grade all the students in the fifth grade enriched math class saying they didn't remember fractions, so maybe I'm the only one who ever retained something

        --
        J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
        • I think Bush is a jackass because all evidence I see points toward him being a brainless puppet for the Washington insiders who form his cabinet. He can't speak or think on his feet at all. The man's the public face of our nation at a time when international relationships are critically important to our future, and there are thirteen year olds taking public speaking classes who can do better.

          The Daily Show this week had an amazing clip, where he was just plain embarrassing trying to do the "fool me once

  • Funny you should mention that. On the most recent Geek Cruise [geekcruises.com], I saw a Holland America shipboard merchant sign [stonehenge.com] that seemed to have excessive apostrophitis. I went into the store to complain, and the lady at the register looked at me like I was from Mars for complaining. Well, as much as a Holland America staff person is allowed to look at me like that anyway. {grin}

    Perhaps people don't get how unprofessional that looks. Perhaps people don't even understand that it's wrong!

    --
    • Randal L. Schwartz
    • Stonehenge
  • People are used to thinking about the world in terms of other people and the things that other people do. Both grammar and thought break down when you try to factor the people out of a situation. If your writing is a sea of nominalizations ("requirements" instead of "you need", "suppositions" instead of "he thinks") or passive verb-forms, you're in trouble.

    Recent bad examples I saw:

    "[module] is best used when a data import or export is required but the task cannot be completed in a single pass"

    or

    "

    • Yes! "The use of" is another nothing phrase that gets deleted as soon as I see it. "The use of marijuana induces a high" vs "Marijuana induces a high". "The use of [SQL syntax] allows this procedure" vs "[SQL syntax] allows this procedure".

      --Nat

  • Wow, this really seems to have gotten people up in arms.

    I'm surprised nobody's mentioned William Safire's "Rules for Writers". It's a document where every sentence violates the rule it mentions. There are several incarnations on the web [google.com], although this one [gla.ac.uk] seems the most popular.

  • Do your authors not know The Elements Of Style? Maybe it should be a contract signing bonus: The O'Reilly Imprint of Strunk & White.
    --

    --
    xoa

    • Actually, we talked for a while about putting together a care package of Don't Write Like The President Speaks books, but eventually decided it'd be cheaper and easier in the long run to just have people write sample chapters first :-)

      --Nat