what we talk about when we talk about coding (open source bridge 6/21)

What We Talk About When

We Talk About Coding

Zoe Landon | @hupfen

The title here isn't a reference to Raymond Carver's book, What We Talk About When We Talk About Love. Just for the record.

This came to me when my book group was discussing a pair of books about running and how they approached the subject very differently.

Haruki Murakami is a novelist, who happens to run.

He took the novelist's approach: telling the story of his fascination with running in a way meant foremost to engage the reader.

Scott Jurek is a runner, who happened to write a book.

He took the expert's approach: using his story and experience to deliver details of what he's done as a runner, and how.

These are both valid approaches. Jurek's is incredibly impressive to runners. But, Murakami's proves much more interesting to non-runners because of that focus on engaging and accessible story.

We can do this

with software.

Not only can we do this - provide engaging and accessible stories that open up software to others - sometimes, we have to.

Consider Oracle v. Google.

“ I don't know what the witness just said. The thing about the breakfast menu makes no sense.

-- Judge William Alsup

Experts on software have been trying - and, sometimes, failing - to explain software jargon to people in a way that makes sense. They may prefer to just use jargon, but that's not an option.

Jargon sucks for outsiders.

Many authors - like Murakami - force themselves to use straightforward language whenever they can. Which makes plenty of sense; they want to be widely read. So there are a lot of thoughts on the subject.

“ Never use a long word when a short one will do. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. -- Eric Arthur Blair

Eric Blair has six rules in total. Including:

"Break any of these rules sooner than say anything outright barbarous."

Using accessible language isn't about dumbing things down. It's about clearing up complicated topics and avoiding unnecessary challenge.(Programming is hard enough on its own.)

LEARNING CURVE

For front end web developers, AngularJS has a reputation for its steep learning curve.

There are a lot of reasons for this, but its choice of language is among them.

Example:

AngularJS has the concept of "transclusion." It's the exact correct word for what's happening, but it's a very uncommon word. Even developers don't always use it.

ReactJS refers to this concept as "child components."

It's a metaphor, but one that works intuitively. It gets the point across clearly enough to work.

Consider Mr.

Smith.

Mr. Smith

Goes to Washing

ton

via Wikipedia

Mr. Smith was a scoutmaster. Not a lawyer or politician or anyone privy to the jargon of writing law.

There was too much to learn too quickly. He was set up to fail.

COGNITIVE LOAD

No matter how smart Mr. Smith was, law - or programming, or anything else - carries with it an intrinsic level of cognitive load. The brain can only handle so much, and the activity always takes that amount up.

For some people, the load of a task is always too much. And that's fine.

Sometimes, the load is too high because of the teacher.

“ … [W]e can hypothesize that presentation techniques frequently result in high levels of extraneous cognitive load that influence the degree to which learning can be facilitated.

-- Paul Chandler & John Sweller

When teaching a concept, it's possible - easy, sometimes - to provide too much information, or provide it in a way that creates extraneous cognitive load. It makes learning more difficult than it should be.

(Intrinsic and extraneous load is the jargon of the concept, by the way. Hopefully I've explained well enough what those terms mean as I used them. That's one way to minimize extraneous load.)

Usually, using jargon is accidental. It's so natural we don't think about it. It can be hard to catch.

However, among jargon's uses is intentional exclusion.

SHIBBOLETH

A shibboleth is a concept - a word or phrase, for example - meant to filter out who's part of an "in" group and who's part of the "out" group.

These are used a lot in war situations. If you can't identify someone from a distance, but their accent really sounds like the enemy… Well, soldiers would shoot on sound.

We're not as violent. But along with using technical terms for this, groups start to use imagery, references, or "in jokes" to filter people out.They start to develop culture by reference.

CultureBy

Reference

(That was not to call out GitHub.)

But, the Octocat is a bit of a shibboleth in open source. It's assumed that everyone in the group recognizes it and what it means.

But the usage can be more severe.Projects with obtuse naming conventions, fitting some sci-fi the programmer enjoyed.Entire offices made of references to 80's TV shows.

Shibboleths aren't even about using jargon, yet leaving terms unexplained is a very common way to put people in an "out" group.

So, jargon must avoided, right?

The case for jargon

It wouldn't exist if it wasn't useful.

In fact, there are a few key points where jargon is almost necessary.

The goal isn't to avoid jargon, but to use it at the right times.

SPECIFICITY

Law has to be incredibly specific. It has consequences, after all, and specificity helps to avoid disputes.

It also has to set boundaries. It has to cover all the bases.

Don't worry about

trying to read

these.

Pronoun's Terms

of Use

On the left is the "human readable" version.

Because there are so many details to ebook publishing (what Pronoun does), even the "simple" version is long.

On the right is the full, legally-binding version.

Reducing jargon doesn't do too much if a high level of detail and specificity is required in the first place.

Sometimes you do want to minimize jargon. Like, say, explaining things to a jury in a court of law.

But that contract you're disputing better be jargon-filled & specific.

ImplicitDescript

ion

Myocardial

Infarction

That's enough about law. Let's talk about medicine instead.

A myocardial infarction is better known to many as a "heart attack." It's a metaphor. But the jargon is really good.

There are three parts:

⊙Myo- (muscle)⊙Cardial (heart)⊙Infarction

(tissue death)

The pieces are the jargon a doctor has to learn.

When jargon is assembled well, someone only needs to learn a few terms in order to understand far more concepts.

(This is a "good" type of cognitive load, by the way.)

SIMPLICITY

The whole reason jargon exists is to explain complex things simply. So long as everyone involved has borne that initial cognitive load, and the jargon actually is simpler than the concept, jargon can simplify language.

Making sure that initial load has been passed is vital. Otherwise, the jargon is left misunderstood, and it falls back into being a shibboleth. That's a problem.

But we solve

problems.

Instructional

Design

This overall domain is part of the work of instructional design. There's a lot of psychology involved, and plenty of UI/UX opportunities associated with it.

Even if you're not interested in that field, there's value in reducing your use of jargon.

How do we approach the problem, then?

COMMON LANGUAGE

The best focus is on reducing extraneous cognitive load. Using familiar language is a solid way to do that. Ideas can be broken down to extremely simple language.

Thing Explaine

r

The book is a little over-the-top, but it shows that you can achieve specificity and simplicity without using jargon.

It can be interesting to force yourself to do it.

Cleartext

This app limits you to the 1,000 most common English words. The output is often, as Eric Blair said, "outright barbarous." But it's great for illustrating how much we rely on jargon.

Cleartext

Even though it was a bit of a joke, people had… reactions.

Very strong reactions.

Very negative reactions.

Morten (the app's creator) brushes it off, but personally, I find it almost horrifying that people would be so hostile about being understood more easily. The whole point of language is to be understood by others.

But anyway.

There are other ways to express ideas that have similar benefits. Instead of reducing extraneous load, we increase germane load.

Accessible

Metaphor

via The Telegraph

Germane cognitive load is "good" load. It helps the student form useful associations and systems.

A good metaphor can kickstart that association process. A bad one...

“ I don't know what the witness just said. The thing about the breakfast menu makes no sense.

-- Judge William Alsup

...Not so much.

Although, that metaphor (APIs as burgers) was fine. Not great, but it could've worked. It was just delivered poorly. People trust eloquence, not poor delivery.

This assumes that expressing the idea depends on the reference. References that are just for flavor, that work without deeper knowledge, are always welcome because they don't exclude as much.

Metaphor

Subjects

There aren't many subjects you can do this with. For English- speaking Western audiences, Shakespeare is one example. Regardless, cultural knowledge is vital here. It's up to you to know what your audience can relate to.

Considering

Audience

What works in the server room doesn't always work in the boardroom or in the classroom. As the teacher, it's our responsibility to know how to account for that.

This often doesn't mean dumbing anything down. Instead, it's shifting the focus and jargon towards the expertise your audience has.

It takes empathy to do this well.

In general, the best results come from when both sides - student and teacher - are willing to account for the other's experience. It's challenging, active work for everyone involved.

So let's do

something.

REWRITES

Rewriting some documentation is the most immediate way to apply these ideas. For an extreme approach: use Cleartext to rewrite your docs. The result will be outright barbarous, but often illuminating.

For a more reasonable approach, just replace any jargon you can identify with phrases that mean the same thing. Then, trim those down, still using everyday language. Remember Eric Blair's points of advice.

“ Never use a long word when a short one will do. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. -- Eric Arthur Blair

It is possible, when you saw that quote earlier, you wondered why I was calling him Eric Arthur Blair.

Considering people know him as George Orwell.

“ Never use a long word when a short one will do. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. -- George Orwell

CONTEXT SHIFT

If I say something came from Eric Arthur Blair, it doesn't bring much context with it.

You may guess some details about Blair, but for the most part, you'd take what's said at face value.

But, since George Orwell is well-known, his name carries a certain context.

Say "Orwell", and now his advice relates to 1984, Animal Farm, all sorts of politics around language.

Try putting your writing in a different context.

Have someone else deliver it.

Deliver it in a new environment.

It's possible someone just won't trust you, for whatever reason - gender, past behavior, whatever.

It may be that you need to talk to an entirely different person.

ExplainIt To

Someone

Ask your mom. Ask your lawyer. Explain what you do, what your project does, to someone who isn't technical at all. And keep trying until you get it right.

“ If you can't explain it simply, you don't understand it well enough.

-- Albert Einstein(supposedly)

If you go to tech meetups, you'll probably find someone who can explain their company in five or six words. It's concise and specific, and so full of jargon that it sounds like bulls**t.

Don't be that guy. Pay attention to how you express technical ideas so that you get more than just a polite nod and smile.

You get real understanding.

Thank You!

- Zoe Landon

@hupfen

Links, citations, and slides at:

http://hupfen.com/talks/osbridge

⊙ Presentation template via SlidesCarnival⊙ Images via Unsplash, Death to Stock Photo,

#WOCinTech, Wikipedia, The Telegraph⊙ Book covers via Amazon