Tag Archives: writing

The Discovery Channel Test

Posted on by Leave a comment

Presentations can be boring. Talking about your work can be boring (to other people). When you’re sitting in a talk or a session that you find boring (and you can’t figure out WIIFM – what’s in it for me)… you learn less.

Although we shouldn’t have to use clickbait techniques to satisfy societally decreasing attention spans, it is easier to learn and retain information when it’s interesting. So I encourage all of you to apply the “Discovery Channel Test” to every presentation, talk, or session you contribute to or lead.

The reason I call it the “Discovery Channel Test” is that there used to be a program called City Confidential that was on all the time. Even though City Confidential was a show about murder mysteries, the first half of the one-hour show was about the city or region where the crime occurred. They talked about when the town was first settled, and key families who made the town what it is today. You heard about stories of intrigue, and challenges the town was facing today. They made the story about the town itself so captivating that EVERY SINGLE TIME I was caught off guard when they ended the first half-hour segment with “You’d never believe a murder could happen here.” Through the hundreds of times I watched this show, I was always shocked when this point came. “Oh, yeah… this is where that murder mystery happened, and we’re about to find out about it.”

Any production crew that can spend a half hour off-topic, keep me interested, and give me a dopamine burst right before the main point of the show… has achieved something great. And you, too, can achieve this same greatness when you’re talking about your tech stack or a new architectural initiative or that project you did last year that improved customer sat. Make it interesting by applying….

The Discovery Channel Test (* = could also be called The Good Podcast Test)

Rule 1: Use an emotional hook up front. Why should any of the people in your audience not leave after the first five minutes? Don’t make them guess! Tell them specifically why this topic might be interesting, or surprise them with an initial feeling of novelty or unexpectedness. Jonathan Lipnicki’s character in Jerry Maguire (1996) was great at this, with his “did you know?” questions. The dopamine surge you create with an emotional hook will keep them engaged for long enough to get hooked on your story.

Rule 2: Find the wow nugget(s). This is one of the things the Discovery Channel has always been really good at: getting me interested in things that I didn’t think were interesting to me. Remember that your projects and initiatives, no matter how cool they are to you, will be boring to other people unless you TRY to make them interesting. I try to tell my high schooler that even in the most boring classes you should be able to find some nugget, some angle, some insight that helps you see the subject matter in a way that grabs you. Find that angle for your audience, and then spoon feed it to them.

Rule 3: Use examples, screen shots, visuals, diagrams. If your presentations are full of slides with words, people will start yawning immediately and may or may not actually hear those words. You can also reduce ambiguity with examples and screen shots. For example, saying “we used Python for this project” is far less compelling than showing the tree structure of the code (or a simplified diagram) and annotating it with what each piece did to get the overall job done. Saying “we used Confluence” is less compelling than saying “we set up a confluence site at [this location] and agreed to put [this kind of information in there]” because if someone has a need for [that information] – at least they know a first place they can look for it.

Rule 4: Spoon feed the closing thoughts. At the very end, remind people what you want them to remember when they leave. Remind people why that’s interesting, and how it might benefit them in the future. Make it concrete and tangible. For example, can you give them reference material, or an infographic, or a checklist that they can use in the future? Don’t assume that people will get something out of your presentation just by attending… spoon feed what you WANT them to get out of it.

“Documentation” is a Dirty Word

Posted on by Leave a comment

I just skimmed through another 20 page planning document, written in old-school “requirements specification”-ese with a hefty dose of ambiguity. You know, things like “the Project Manager shall…” and “the technical team will respond to bugs.”

There’s a lot of good content in there. It’s not easy to get at, though… for each page I want to understand, I can expect to spend between ten minutes and an hour deciphering what’s going on. (That’s half a week of work, and I have a lot of other work to do this week. Is it even worth it?)

Also, this document is boring… and there’s a lot of filler (like “package X is useful, flexible, and open source” – OK, that’s great, and factually correct, but not very informative).

The whole document could have been condensed into 4 or 5 slides of diagrams plus annotations. If that had happened, I’d be looking at a 10 to 30 minute commitment overall to get my brain into this particular company’s context… and then I’d be able to make some useful contributions. (As it stands, I’m weighing whether it’s worth my time to go spelunking in that 20-pager at all. Probably not.)

Unfortunately:

  • The bulk of technical documentation that I read is unintelligible or lacks sufficient meaning. I have three decades of exposure to this stuff, so if I can’t understand it, I feel super sorry for the early career people (who might think they can’t understand it because they don’t know enough).
  • Nearly all of the technical documents I see are uninteresting. And tech is interesting.

99 times out of 100, technical documentation is dull and dysfunctional. While it’s supposed to help people and teams establish a shared understanding of a system or a process or a concept, it just ends up looking really impressive and convincing you that the authors know a lot more about this than you do. It doesn’t help you much, if at all.

And as a CTO, CIO, or VP of Engineering, I don’t want to pay for crappy documentation. This particular document probably cost me between $32K-50K, and that’s just the tip of the iceberg… because it doesn’t account for the incremental costs of the people who will attempt to decipher it – which could be 10-100x more over the lifetime of that document. Although the person or team that wrote the 20-pager probably knows what’s going on (at least a little bit), the artifact itself is going to cost other people time and take them away from more value-adding tasks.

The sheer volume of information we’re required to wade through to gain understanding – without the assurance that it will lead us in the right direction, or even in any direction at all – is probably what’s led to the disease of devaluing documentation. 

A lot of managers think documentation isn’t value-adding, and shouldn’t be done, because… in most cases, people do it so badly that it wasn’t worth the investment in the first place.

Dear tech workers: can we fix this, please? I know it will take a whole generation to effect meaningful change, but… I’m ready to roll up my sleeves.

Improve Writing Quality with Speaking & Storyboarding

Posted on by One comment

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.

Me, Reviewing Someone Else’s Work

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.

What Just Happened?

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.

What Can You Do?

Here 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.

Storyboarding

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.

Next Steps

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!

STORYBOARD (BLANK)

STORYBOARD (PARTIALLY FILLED IN)

Writing a Great Article Review

Posted on by One comment

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

Posted on by One comment

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

Posted on by 7 comments

(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.