Explaining Hard Things to Humans

The Principles of Effective Technical Communication

Follow along at:
http://wpshout.com/wclax/index.html

Review this presentation at:
http://wclax.reviews/

Hi! I'm Fred

WPShout | wpshout.com | @wpshout

Press Up | pressupinc.com | @pressupinc

Follow along at:
http://wpshout.com/wclax/index.html

Review this presentation at:
http://wclax.reviews/

What Technical Communication Is

"Explaining hard things to humans"

Hard Things

Things that take a lot of specific technical knowledge

Technical knowledge: Knowledge that is mostly unrelated to human intuition

Explaining

Conveying knowledge effectively enough that a specific goal is achieved

  • For a technical coworker, goal may be perfect understanding
  • For a client, goal may be simple general intuition for decisionmaking

To Humans

  • Imperfectly rational
  • Limited processing power
  • Different learning patterns, strengths, and interests
  • Insecurities (don't like to feel uninformed)
  • Emotions (don't like to be talked down to)

…You're a human too :/

Why This Matters

The goals we mentioned before

"My cousin says he can build this site with Yahoo's free page builder. Tell me what's wrong with that in language that convinces me."

"WordPress sounds good for this project, but my boss is worried: don't people say that WordPress is easy to hack?"

"I bought your plugin, but the documentation makes no sense and I want a refund."

Technical Knowledge: You're On a Hill

The Hill and You

  • Getting up the hill took effort
  • Being up there comes with an amazing view, which lets you see and do lots of cool stuff
  • You're passionate about the stuff—that's why you climbed the hill!

The Valley and Its People

A perfectly wonderful place to be

But may sometimes need "hilltop" information

This could mean you need to provide:

  • Instructions for climbing the hill
  • Probably more commonly: A hilltop report that valley people can understand

The Challenge:

Knowledge Gaps

Not just a lack of specific knowledge

A lack of entire knowledge contexts

The Result (Sometimes):

Attitude Problems

1. Arrogance

Arrogance

What It Looks Like

  • Curt, standoffish, constantly put-upon
  • Refusal to simplify into terms others will understand
  • Testing others: "Do you know X?" as an accusation
  • Causing Impostor Syndrome in others
  • Indifference to whether others understand you or not: "I could always fall back on being right"

Arrogance

Where It Comes From

Sometimes from insecurity, bad manners, big egos, etc.

More often, from a love of clarity: Confused people bring confusion, not clarity, so they're an obstacle

Why try to explain your view to people who, by definition, can't understand?

2. Breeziness

Breeziness

What it Looks Like

  • Overload—exceeding others' ability to learn
  • Explanations with too much tacit knowledge
  • Sailing over others' heads: skipping the basics and diving into advanced topics others don't understand
  • Continually emphasizing how easy, simple, logical, etc., one's own knowledge is
  • Enthusiasm as an impediment to communication

Breeziness

Where it Comes From

Love of the hilltop

The view is so cool, and it's sitting right there!

(…To you, on the hilltop)

The Basic Problem:

Blinded By The View

Your knowledge is so important to you that you can't properly communicate with people who need elements of that knowledge

The Right Attitude:

1. Audience-Aware

2. Strategic

1. Audience-Aware

Always Start Where Your Audience Is

Reason carefully and without bias about the extent of others' knowledge

Your communication must reflect this understanding, and respect differences in knowledge

Audience-Aware Strategies

Use Analogies

Analogies phrase your understanding in terms of your audience's understanding—they are hugely valuable!

"How does WordPress work?"

(Asked by someone just learning CMSes)

1. WordPress stores post and other data in its MySQL database, and uses a PHP codebase compiled from WordPress's core functionality, custom-build themes, and optional third-party plugins to dynamically render that data.

2. WordPress is a factory that builds webpages! Database: warehouse. PHP processing: factory. Themes: assembly lines. Plugins: outside contractors.

Manually List Knowledge Dependencies

Tacit knowledge is the air that makes Breeziness breezy!

Make clear:

  1. Precisely how far up the hill are we starting?
  2. Are we skipping any steps on the way up?
  3. If yes to #2: Why, and where can I learn those steps?

"Grunt: Getting Started"

"Grunt and Grunt plugins are installed and managed via npm, the Node.js package manager. Grunt 0.4.x requires stable Node.js versions >= 0.8.0. Odd version numbers of Node.js are considered unstable development versions.

Before setting up Grunt ensure that your npm is up-to-date by running npm update -g npm (this might require sudo on certain systems)."

…but I am PC Peasant! :(

I could be part of Grunt, but its documentation is absolutely not for me

How about at least a linked intro to using the command line in different systems?

2. Communicate Strategically

  1. Reason about the goal of the communication
  2. Always tailor your communication to that goal

"What is WordPress?"

(Asked by a potential client)

1. WordPress is a free and open-source content management system based on PHP and MySQL. Features include a plugin architecture and a template system.

2. WordPress makes it easy for you to use your website, and it also makes it quicker and easier for us to build your site. We'd be happy to explain more about how.

In Your Own Writing

1. Basically, a conditional tag is just a function that…

2. A conditional tag is a function that…

1. Nothing too out-of-the-ordinary here. Basically, we just do the stylesheet enqueuing as normal, but we've wrapped it in a simple if-statement

2. Here, we enqueue our stylesheets as we described previously, but we've wrapped the enqueue commands in an if-statement

1. Success! WordPress has been installed. Were you expecting more steps? Sorry to disappoint.

2. Success! WordPress has been installed. Thank you, and enjoy!

Thinking strategically can really improve your writing!

No

1. Arrogant

2. Breezy

Yes

1. Audience-Aware

2. Strategic

A Final Note on Empathy

You can do all this right and still not be very nice

Tense people resist learning

How to Have Empathy

in Two Simple Hacks

Speaking: Smile as you talk, see what changes

Writing: Put a :) after every paragraph, delete anything that looks sarcastic

Thank You!



wpshout.com | @wpshout


Review this presentation at:
http://wclax.reviews/