Skip to Content

When I started my professional career, more than 30 years ago, written communications were limited to business letters, signed by a select few officials.  Ordinary staffers where I worked were allowed to draft correspondence, which was typed by a professional secretary, for a manager to sign.  My sole attribution was my initials (“JES”) somewhere near the bottom of the page.  Even with electric typewriters, turnaround time was slow, with days sometime passing before a communication went down to the mail room to be given to the post office.

Fast forward to the 21st century, where snail mail correspondence is so rare, I can’t remember the last time I got something in the box at work that wasn’t an advertisement, bill, or occasional reference manual, and everyone is empowered to generate their own communications.  From email to forum posts to instant message, we’re all constantly writing to our co-workers, peers at other sites, and to vendors.  As far as technical writing, I think we’re pretty good at opening a trouble ticket, describing a problem, and feeding data to support personnel as needed.

Is there a problem, then?  As I’ve been working on the backlog of un-reviewed blogs, I’ve come across numerous areas of possible improvement, and thought I’d explain via a blog. When I’ve looked on SCN for blog help, it seems to be mainly around how to blog – how to get approval, what buttons to push, how to link, etc.  There isn’t much on style.  There was that absolutely classic Matt Kangas post on “Thoughts from a Forum Moderator” where he exclaimed the necessity of spelling words correctly and completely.

Some of what I’m about to say is covered in Blogging 101 (link at the end), though that wiki page mixes the mechanical “how-to” with the contextual “what” and “why” I’m talking about.

Here are rules I’d like bloggers to understand:

  • Write as you want people to read, not as you want people to hear
  • Proofread your sentences, your spelling, your tired and poor cliches
  • Say less, not more (but don’t use ‘txt spk’)
  • Don’t pitch a product or service, tell us how you built it or how you use it
  • Get advice, and heed it.  Use a muse, a mentor, or a trusted friend.
  • Acknowledge and link to your sources

Write as you want people to read

This is absolutely the hardest of the above rules to obey. First, you need to understand how to cast your written voice in specific ways.  Second, you need to interpret what the audience needs on a particular topic.  Third, you need to keep your chosen voice steady through the work.

And if you don’t know what “voice” is, well, read this post titled “Finding Your Written Voice” – it’s geared toward memoir writing but should work fine for bloggers.

Proofread your sentences

This one is also harder than it sounds.  Spell checking is pretty easy; word checking is harder.  Making sure you said what you meant requires mental discipline and a lot of time.  If you don’t have the time to produce quality work, ask yourself why you are blogging.  The rest of us don’t have time to guess what you meant, or ask you to fix your mistakes (other than us moderators, I suppose).

And if your writing runs to pomposity (as mine does), lean on Samuel Johnson’s advice:

“I would say to Robertson what an old tutor of a college said to one of his pupils:’Read over your compositions, and where ever you meet with a passage which you think is particularly fine, strike it out.'”

Boswell:  Life of Johnson

Say less, not more

I don’t believe this is the same as proofreading, where on careful analysis one can find more economical ways to say what you meant.  This is more about planning, thinking before you write, and above all, leaving out anything unrelated to the topic at hand.  I reviewed a blog on SCN recently where it seemed nearly half the content went through some ancient literature.  Great stuff, but it would have been more effective if limited to no more than one paragraph.

Don’t pitch

These are blogs.  We’re looking for your personal experience.  If you thinly disguise an attempt to sell something, we’ll see right through your writing and never come back.  Ever.

Your blog bio should tell us where you work.  Of course you have to write about what you are working on – what else would you know about?  Make a serious attempt to share the ups and downs of your project team work, and we’ll find it fascinating.

Get advice, and heed it

Junior bloggers will get the luck of the draw, and have their content reviewed by someone who may or may not know much about the subject matter.  Reviewers should and will kick it back if the writing is unintelligible, full of jargon, or has run-on, rambling sentences.  If your writing is marginal, your blog may be released and then the second tier, the wider SCN audience, rips into it.  It’s happened to me, more than once.  As I told Jon Reed, “I like to think I’ve benefited from the slings and arrows of numerous barbs.”

If you have a trusted mentor, great, use them.  I often share my blog ideas with Jon Reed, Marilyn Pratt, Dennis Howlett, and others.  Maybe another SAP Mentor would be willing to critique your work, or if you prefer someone in your office or area, ask around.  Advice is really easy to get.  Hard to apply, but easy to get.

Link to your sources

Having gone to a university than had an honor system, rules for term papers, and working with various technical and scientific journals for decades, it seems second nature to me how to quote and acknowledge source material.  That doesn’t seem to hold true for everyone, though, and it’s been a learning moment for more than one of my mentees.  It’s in the rules of engagement, so it’s quite easy for a moderator/editor to point out the right way.

Linking is more challenging.  You’ll notice I linked 3 references above – one SCN blog, one online publication, and one classic, non-copyrighted quote.

Wrap up

I want to thank Jon Reed for musing with me on this topic.  He liked my borrowing from Shakespeare’s Hamlet for the blog comment barb/barbarism analogy.

The title of this post comes from Mark Twain’s Life On The Mississippi; Twain was talking about steamboat pilots as well as newspaper editors (he was both), and said –

We write frankly and fearlessly but then we “modify” before we print.

(You may note I linked to the Project Gutenberg free edition of the book, rather than the Google sort-of-free version.  I highly recommend the book, and Project Gutenberg’s complete collection of free reading; one of the host sites is in my home town)

Also see:

And, the SCN reference pages, etc.:

One last reference:

  • Effective Writing for Engineers, Managers, Scientists, 2nd Edition, H.J. Tichy, 1988.

I went through the first edition of this book several times years ago; I bought the second edition used for $5 or $10 and am nearly through it.  Heavy going, but worth every minute of study.

To report this post you need to login first.

9 Comments

You must be Logged on to comment or reply to a post.

  1. Vijay Vijayasankar
    I readily admit that I have not lived up to these guidelines every time I posted a blog. And Jim was always there to help point out what needs fixing – and I greatly appreciate him doing that.

    So all I can say after reading this blog is “hear hear” !

    (0) 
  2. Martin Lang
    Loved all your blog rules/guiding principles Jim. I think they are all very true and worthy to think about and take in.
    The “Get advice, and heed it” I experienced myself recently quite a bit. When I asked colleagues or other folks that I trust for advice it actually was quite a rewarding and satisfying experience both to ask for and to give advice.

    The “It’s Complex to Write Simple” comment comes from a blog, which a colleague I contacted for a blog review recently had sent me. It talks about Hemingway’s Rules of Writing. They were in fact the rules of writing of the Kansas City Star newspaper, where Hemingway started his writing career as a cub reporter.

    In short they are:
    1.Use short sentences.
    2.Use short first paragraphs.
    3.Use vigorous English.
    4.Be positive, not negative.

    Find the blog about these here, I found it to be very good and inspiring as well: http://www.writingriffs.com/2009/11/30/hemingways-rules-of-writing/

    (0) 
    1. Jim Spath Post author
      Martin – thanks for the feedback and encouragement, plus the fix DM. Oddly enough, I’ve gotten to Chapter 11 in “Effective Writing for Engineers [et al]” where the topic of “Writing Only Short Sentences” comes up. The author believes this is shortsighted (pun intended) and one should vary sentence length depending on audience, and for variety.

      But that’s their opinion.

      Jim

      (0) 
  3. Marilyn Pratt
    I’ve observed you Jim as one of the most thorough, thoughtful and critical blog READERS around.  No let me amend, Community Content Readers (including of course wiki contents and forum posts).
    I wanted to remind all of us that public response and engagement around the quality of contents is the best way to ensure quality.  Too often we can guess that some folks that are “turned off” by a type of contents refrain from responding and lose interest rather than making an effort to amend or improve.
    We are fortunate that there are folks like yourself, and others you often cite like Jon Reed, Vijay V. and your ASUG colleagues Sue Keohan, Gretchen Lindquist, Karin Tillotson, Chris Solomon and additional folks who monitor activity in forums and blogs like Anton W., Julius B, the Matts, Luis Lanz, Thomas Jung, Darius Heydarian, Benny Schaich-Lebek, Arun Varadarajan, Somnath Manna, Gregor Wolf, Stephen Johannes, Abesh B., Juan Reyes and countless others in many topic areas that really seem to keep a keen watchfulness on the published contents of our community with a critical and helpful eye towards quality and improvement.  Very importantly, they attempt to voice their opinions in the context of the submissions.
    So my advice, if any to give (and take), would be to continue to encourage the “voice of the READER” which in turn can improve the voice of the contributor. Thanks Jim for being both.
    (0) 
  4. Gregory Misiorek
    Jim,

    great advice and it only proves that as in the real world quality comes at a price and extra effort. we are in the new territory, however, and not all that applied to the printed world is 100% transferable to the online world, the most obvious aspect is the speed of, both publishing and obscurity.

    i have been taking the liberty of commenting and responding in forums in the lower case only, but for blogs i do use upper case and i would like to keep it that way and not get slapped by someone’s censorship, which has happened in one of the forums as my help was misinterpreted as “selling” or “cross-posting”.

    i especially like your way of using links or hiding the url’s behind some description (hopefully relevant, at least in my case).
    style is not something we can change easily, just like we don’t want to change the way we eat, dress, etc.

    i also want to speak for non-native users of English as we should appreciate the effort in learning the language and be sometimes more forgiving. other languages are sometimes more dense and elaborate and we were not all English majors.

    with some effort, we can all make it better.

    (0) 
    1. Jim Spath Post author
      Greg:

        It’s great that you shared your differences with what I wrote.  Honestly, it’s ego-enhancing to see positive comments, but rather boring to others.  Let me counter a few of your points:

      – lower case only

        If you are texting, or sending an informal email to friends, I see no problem ignoring the rules of capitalization.  In blog comments that might be read by hundreds or thousands of people, I would avoid this for two reasons.  One, it makes your commentary harder to read, maybe only marginally harder, but why make it difficult for people?  Second, your tone (when you use poor punctuation) comes across as someone in a hurry, not putting much thought into what you are saying or how you are perceived.  I know that is not your intention, nor are you probably in a big hurry, but how hard is it to hold down the shift key every 40 or 50 letters?

      – censorship

      An interesting topic, particularly for someone who is a moderator and communicates with other moderators.  SCN has a set of rules that can’t be crossed, or the content is deleted; I don’t see that as censorship, merely as enforcement of a mutual contract. However, the role of “editor” or “proof-reader” of others’ material is ambiguous.  Telling someone they can’t promote a product might seem like censoring their work, but again, it’s in the rules. I like to think I’m educating by sharing examples of better word usage, not that I am blocking someone’s self-expression.  Once in a while though, gibberish sneaks through that needs pruning.

      – style is not something we can change easily

      I totally agree with this, and will do whatever I can to help those who ask.  I’m not an English professor or professional writer, I just like reading and writing (arithmetic too ;-).

      – non-native users of English

      This topic crossed my mind as I prepared this blog, but I decided I had nothing useful to say.  Certainly the rules of English grammar, spelling, case and tense are obscure, oblique and nonsensical.  And if someone has a “voice” that reads clearly if a little stilted, I won’t comment on their style.  On the other hand, if someone asks for my help, I’ll gladly offer suggestions for rephrasing sentences and ideas into readable prose. Who wants to struggle understanding what the author meant, if the work would read better after improvement hints?

        Thanks again, Greg.

      Jim

      (0) 
  5. Martin English
    Hi Jim (and anyone else reading this),
    I’ve reread some my SDN and personal posts through the filter provided by your ideas here, and have found them wanting.  Now, I don’t believe its a good practice for me to go back and rewrite the older entries, rest assured that future posts will improve !!!

    BTW, thanks for this and for your technical content 🙂

    (0) 

Leave a Reply