Tag Archives: writing

Improve Writing Quality with Speaking & Storyboarding

For a decade, I supervised undergrads and grad students as they were completing writing projects: term papers, semester projects, and of course — capstone projects and thesis work. Today, I’m responsible for editing the work of (and mentoring) junior colleagues. The main lesson I’ve learned over this time is: writing is really hard for most people. So I’m here to help you.

If I had a dollar for every time this scenario happened, I’d… well, you get my point:

ME (reading their “final draft”): [Voice in Head] Huh? Wow, that sentence is long. OK, start it again. I don’t understand what they’re saying. What are they trying to say? This doesn’t make any sense. It could mean… no, that’s not it. Maybe they mean… nope, that can’t be it.

ME: So this sentence here, the one that says “Start by commutating and telling the story of what the purpose of the company’s quality management software is, the implementation plans and the impact to the current state of quality roles and responsibilities for everyone involved.”

THEM (laughing): Oh! Commutating isn’t a word. I meant communicating.

ME: Have you tried reading this sentence out loud?

THEM (still laughing, trying to read it): Yeah, that doesn’t really make sense.

ME: What were you trying to say?

THEM: I was trying to say “Start by explaining how quality management software will impact everyone’s roles and responsibilities.”

ME: Well, why don’t you say that?

THEM: You mean I can just say that? Don’t I need to make it sound good?

ME: You did just make it sound good when you said what you were trying to say.

By trying to “make it sound good” — it’s more likely that you’ll mess it up. People think speaking and writing are two different practices, but when you write, it’s really important that when you speak it out loud, it sounds like you’re a human talking to another human. If you wouldn’t say what you wrote to someone in your target audience in exactly the way that you wrote it, then you need to revise it to something you would say.

Why? Because people read text using the voice in their heads. It’s a speaking voice! So give it good, easy, flowing sentences to speak to itself with.

There are two ways you can start improving your writing today:

  1. Read your writing out loud (preferably to someone else who’s not familiar with your topic, or a collaborator). If it doesn’t sound right, it’s not right.
  2. Use a storyboard. (What does that mean?)

There are many storyboard templates available online, but the storyboard attached to this post is geared towards developing the skills needed for technical writing. (That is, writing where it’s important to support your statements with citations that can be validated.) Not only does citing sources add credibility, but it also gives your reader more material to read if they want to go deeper.

The process is simple: start by outlining your main message. That means:

  1. Figure out meaningful section headers that are meaningful on their own.
  2. Within each section, write a complete phrase or sentence to describe the main point of each paragraph or small group of paragraphs
  3. For each phrase or sentence that forms your story, cut and paste material from your references that supports your point, and list the citation (I prefer APA style) so you don’t forget it.
  4. Read the list of section headers and main points out loud. If this story, spoken, hangs together and is logical and complete — there’s a good chance your fully written story will as well.

Not all elements of your story need citations, but many of them will.

When the storyboard is complete, what should you do next? Sometimes, I hand it to a collaborator to flesh it out. Other times, I’ll put it aside for a few days or weeks, and then pick it up later when my mind is fresh. Whatever approach you use, this will help you organize your thoughts and citations, and help you form a story line that’s complete and understandable. Hope this helps get you started!




Writing a Great Article Review

We’re teaching a class on blockchain and cryptocurrencies this semester, and since the field is so new and changing rapidly, we’ve asked our students to make finding and reviewing articles part of their learning practice this semester. This is a particularly challenging topic for this task because there’s so much hype, marketing, and fluff around these topics. We want to slice through that, and improve the signal-to-noise for people new to learning about blockchain and cryptocurrencies. Here are some tips I just prepared for our students — they may be helpful to anyone writing article reviews, especially for technology-related areas.

0 – Type of Source. Reviews or articles from from arXiv, Google Scholar were strong; reviews from Coindesk, CNN were weak; reviews from WSJ and Hacker Noon went both ways. Here are two submissions that were publishable with only minor edits:

1 – Spelling & Grammar. Most of you are college seniors, and the few who aren’t… are juniors. Please use complete sentences that make sense, with words that are spelled correctly! If this is hard for you, remember that every one of you has spell check. One way to remember this is to draft your posts in Word, and then perform spell check before you copy and paste what you wrote into WordPress.

1 – Your job is to create the TL;DR. What’s the essential substance of the source you’re reviewing? What are the main lessons or findings? If you were taking notes for an exam, what elements would you capture? (Using this perspective, commentary about how good or bad you think the article was, or what it didn’t cover well, would not help you on an exam.)

2 – Choose solid source material — primary sources, e.g. research papers, if possible. If the article is less than ~400-500 words, it’s probably not detailed enough to write a 250-300 word summary/analysis. Your job in this class is to break down complex topics & help people understand them. If your article is short and already very easy to understand, there’s nothing for you to do.

3 – Avoid “weasel words” (phrases or sentences that sound like marketing or clickbait but actually say nothing) and words/sentences that sound like you’re writing a Yelp or Amazon review rather than a critical academic review. Here are a couple weaselly examples drawn from this week’s draft posts (see if you can spot what’s wrong):

  • It is clear how beneficial blockchain can be to smaller businesses.
  • Blockchain has the potential to change the world.
  • Each other the topics covered in the article deserve their own piece and could be augmented upon greatly.
  • There is a degree of uncertainty that comes with an emerging technology.
  • Blockchain can bring them into the 21st century to compete with larger corporations.
  • Many people are scared of the changes, and governments will seek to regulate it.

4 – Answer the “so what” question. Why is this topic interesting or compelling?

5 – Choose information-rich tags. For example, in our class, don’t include blockchain as a tag… pretty much everything we do will be related to blockchain, and everyone will tend to use it, so there won’t be much information contained in the tag.

Improving the Quality of Your Writing

blacked-outMorgan and I work with students to produce written reports all the time. Sometimes, they’re working on their senior capstone project, which culminates in a formal written thesis… other times, they are working on shorter reports. Ultimately, the goal of writing is to produce an artifact that will effectively communicate a specific message to a specific audience. What people don’t as easily recognize, however, is that for this to occur — the audience has to understand what you’re trying to say.  Since we’re academics, we write all the time (sometimes well, and sometimes badly). We’re used to writing one draft, and then another, and then another… serving as our own worst critic every time we pick up the paper with fresh new eyes. Sometimes, we benefit from the critiques of an external reviewer, and when we hear what they have to say — more often than not, we say “yep, I didn’t do that part well… I’ll try again.” And then we try again and again, never really getting it perfect, but sometimes getting it close.

What follows are some comments Morgan provided to one of our students after the student submitted a portion of a thesis draft for us to review. We quickly realized that we could give almost all of our students the exact same advice. So here are some tips to help you improve the quality of your writing… and it usually starts with eliminating most of what you started with.

Let’s start with the quality of your writing. This feedback may come across as harsh, but it is not intended to be so. Please rest assured that Nicole and I have your best interests at heart, and since this is perhaps one of the last opportunities you’ll have in your educational career to get detailed, personal feedback on your writing, we feel it is our responsibility to be blunt and honest with you. This may be your last chance to really work to improve before you enter a professional setting. So you might want to brace yourself because this may sting.

Okay, here’s the bad news: your writing is shockingly bad. If I didn’t know better, I would be convinced that English is not your native language. If you were to write like this in a professional setting, you would certainly embarrass yourself and it might actually damage your career.

The good news is that you can improve and we’re going to help you. Before I make specific guidance on your draft, I’d like you to take the first stab at revising what you’ve written so far. Here are your instructions. Please follow them closely.

Do not spend any time apologizing to us, or making excuses for your writing. Everyone starts somewhere. You need to not be self-conscious, and be open to really working on getting better.

Stand or sit in front of a mirror and read what you wrote out loud to yourself. I’m totally serious about this. It may feel silly to you, but it will help tremendously. I know from talking to you that you talk and communicate like a totally normal person. I also know from experience teaching many people that it is not uncommon for people, who can have normal conversations, to totally fall apart when they try to communicate in writing. As you read your paper to yourself, imagine that you are listening to someone else read this paper to you and that it is not your own work. Trust your gut. If it sounds weird or bad, it probably is.

Every time you hear a sentence that sounds strange, put a mark on the paper to indicate that the sentence needs to be revised, but don’t make any changes yet.

Once you’ve read the whole paper out loud to yourself, go through the paper again. Read each sentence one by one and ask yourself the following questions:

  • What was the purpose of this sentence?
  • What vital information does it convey?
  • Could it be said in a much simpler, more direct way?
  • If I erased this sentence altogether, would it change the meaning or impact of the paragraph?
  • What was I trying to say? Listen to the words that just came out of your mouth when you answered that question. Why didn’t you just say that?
  • Is there anything else I could do to improve this sentence?

If the answer to questions 1 and 2 are “I don’t know” or “none” then you should delete the sentence. If you get to question 3 and the answer is “yes” then revise the sentence to make it shorter and more direct. For question 4, read the whole paragraph leaving out this sentence. If the meaning of the paragraph doesn’t change, then delete the sentence. If the sentence is still there and you get to question 5, then make any final changes and move on.

You might find that you need to revise earlier sentences based on changes you make on later sentences. It’s okay to go back.

As you do this, don’t be discouraged. Persevere. This should be tough, but I think you’ll find several things:

  • Your draft will probably be 50% shorter without losing any meaning. This is a GOOD thing!!!
  • It will feel much better and be much easier to understand, both for yourself and for other people.

Here are a couple of other pointers:

  • Don’t use an inflated font size.
  • I know for a fact that the default font size in Google Docs is not 14. Just stick to the default, which is 11. Regardless of whether this was your intention, boosting the font size makes it look like you’re trying to make us think you wrote more than you did. Since shorter is better, this doesn’t help you in any way.
  • Stick to single spacing.
  • Again, stick with the default. You can take care of formatting the document at the very end, after you know that you’ve got the content right.

A lot of this restates the feedback we give you in every one of the classes you’ve taken with us. Keep it simple. Keep it direct. Only include a sentence if it really adds something to the narrative.

Unless they really convey something crucial, leave out images for the time being. Don’t include images just to make the report “look pretty” or to take up space. Pretend you’re writing for Wikipedia. Include the facts, just the facts, and nothing but the facts. Don’t embellish.

Don’t try to make it fluffy or sound like marketing. Keep it clean. Keep it objective.

Okay, whew. I know I’ve just thrown a lot at you, but stay positive. My goal is not to tear you down, but to support you in getting better. This is uncomfortable sometimes. You are working on really amazing stuff and I have confidence in you that you can do something that we’ll all be proud of. Hang in there!

An Unorthodox Tip for Improving Productivity and Eliminating Writer’s Block: Listen to the Earworm

(Image Credit: Doug Buckley of http://hyperactive.to)

The other day I read a news article or blog post (or something; I can’t remember) that explained one reason we get irritating songs stuck in our heads. The post was based on a research paper by Williamson et al. (2011) in the journal Psychology of Music. Usually, when we catch one of these “earworms” because we’ve heard a snippet of a catchy and familiar song, we’ll walk away or turn off the song in the beginning or the middle of it.

The tune, however, like a rapid flesh-eating organism invading our very soul, continues without compunction. Because we stopped the song in the middle, our unconscious becomes fixed on the task of finishing it. And so it continues, on and on, all day!

The solution, we’re told, is to listen to the annoying song until it’s over… our unconscious, at that point, will be content that the tune is complete and will be happy to move on to other topics.

I didn’t think too much of this piece of trivia until I was reading an interview with Erik Larson, author of the fantastic 2003 novel The Devil in the White City. His book provides an amazing account of the technology development and social context that went into organizing the 1893 World’s Fair in Chicago – it’s a totally satisfying read. When asked about his discipline for writing, and for avoiding writer’s block, he described a method that might actually leverage the same hold on the unconscious that earworms grab:

And I try to write a couple of pages. I’m not firm. I don’t have a specific goal. But the one thing I always adhere to is that I stop while I’m ahead. If I’m going to take that break for breakfast, I may stop in the middle of the sentence or the middle of the paragraph. Something I know how to finish. Because as any writer knows, it’s — that’s what kills you is when you just don’t know what to do when you come back. And all the demons accumulate. And then you go out for a cappuccino, that kind of thing.

If you want to avoid writer’s block, leave your unconscious a hook – an easy way back in to your writing productivity!

If you want to avoid ramp-up time (or context switching time) to get your head back into a problem – which has been estimated, for software development at least, to be on average a full 15 minutes for every interruption – leave your unconscious an easy way back in to productivity! A half written module or subroutine… or a half written sentence on your notepad!

These are just hypotheses, but they’re definitely testable. I’m going to try testing this out in my own life immediately.