The last S in the popular acronym K.I.S.S.  (Keep it Simple Stupid) needs to be emphasized.  It is told to someone who is being intellectually lazy, which implies that those who keep it simple are the ones using their gray matter effectively.  The world needs to be more conscious that information is not transmitted magically.  It requires both acknowledgement of the gap between neurons in distinct minds, and also creativity to reshape a block of knowledge into a way that caters to the listeners.

Briefly digressing, open-source software is free, publicly available software, which powers much of the internet.  It’s also permitted to modify it to your specific purposes.  Closed-source software is the opposite, and benefits only one person or company.  Open-source thrives not on profit, but rather on public awareness and a sense of community, due to it being dependent on reciprocation in some form.

I attended a conference on open-source software, OSCON 2013, and I witnessed a tragedy.  The U.S. government sponsors a web site, http://www.whitehouse.gov, which promotes “Open Government”, “Open Data”, and “Open-Source”.  See the mission of this specific department here:  http://www.whitehouse.gov/developers.  At OSCON 2013, Leigh Heyman, Director of New Media Technologies for the Executive Office of the President, showed us a video.

It was a simple interaction between himself and none other than President Barack Obama himself, where the President inquires to Leigh what his department is working on next.  Leigh responded with “APIs”.  The President parroted his words, and then, as you might expect from a seasoned officeholder, jocularly conceded he had no idea what an API was, followed by laughter throughout the room.  We at OSCON laughed as well, taking pride in the moment where “a techie like us” got the President to utter a technical acronym.  However, this was nothing less than a potentially tremendous but lost opportunity.  While API, Application Programming Interface, is one of the most common technical terms in modern software engineering, it’s still a technical acronym that no one should expect the listener to have knowledge of. Leigh, instead, could have said “We’re developing an interface for other software to access our data easily over the internet.”

The Director of a publicly-funded, high-exposure technology department should certainly have prepared in advance a simple, canned summary of the future direction of his group’s efforts.  Effective elevator pitch-style explanations are not easy to create, but if you want to be able to consistently explain something on a moment’s notice, you must think it through and practice.  This was a rare opportunity to transfer knowledge of the benefits of the open-source community and data sharing to a figure of such influence.  Instead, this was reduced to a cute moment where “the open-source community affected something high-profile”.  The recent George Zimmerman trial was interrupted when a witness gave testimony remotely via the internet (using Skype).  People sent chat requests to the witness, able to interrupt something on public television.  That is what Leigh’s interaction with the President equated to, and it could have been so much more.  Speaking directly to the President is not in any way relying on the Butterfly Effect to advance your goals.

Fast-forward to another much more technical talk at OSCON, on improving the performance of TCP, delivered by Jason Cook of a digital content delivery internet company, Fastly.  TCP is one of the core methods by which computers on the internet can communicate.  Hoping for deeper level insights into the subtleties of TCP, I attended this talk.

Jason started by talking about how TCP works, mentioning how two computers initiate communication sending “SYNs” and “ACKs” to each other.  I personally have dove deep into TCP before, and realized he was describing the “handshaking” procedure two computers use to start communicating with each other.  I knew TCP confirms messages are received by using “ACK”nowledgement messages, but I forgot why messages are called SYNs.  Most programmers communicate through TCP using pre-built functionality that alleviates concerns of the inner workings of TCP, but here, the speaker was assuming those attending his talk would be familiar with it, reviewing some key points.  He was also using acronyms that many in the audience would not understand.  He continued from there speaking very fast, using equally technical terminology.

This demonstrates a couple of additional problems.  If you only cater to a particular level of expertise, your audience should be appropriately filtered, perhaps by explicit language in the abstract of a talk.  It is true Jason only had limited time to cover the intended subject matter, but if he wanted to educate a wider audience, he should have pared down the information as necessary to allow for more explanation and cogitationwithin the minds in his audience, which could have included anyone within the open-source community.

Before I personally write or say anything, I run it against what I want to assume the reader or listener knows.  Perhaps I shouldn’t have assumed people know who George Zimmerman is, but enough do, and the point I was making was not dependent on this knowledge.  However, I did not assume you knew what TCP was.  Most programmers today would know what TCP is, but I want non-programmers to understand everything in this article too.  I did not tell you that TCP stood for “Transmission Control Protocol” because I wanted to keep it simple and not distract.  Being able to write or speak in a way that, for a target audience, is understandable by most if not all of them, and yet does not stray significantly from the over-arching purpose, is not an easy task, but should be the intention of any individual that endeavors to communicate

I recently wrote an article on Git, a popular open-source software used to store the incremental versions of software code.  At first, I only intended to write an article about how I use it, but then I realized I would like the article to be useful to anyone just getting into programming who may not necessarily be familiar with Git.  I proceeded to add a very lengthy tutorial, with small steps and plenty of screen shots.  It’s true there are many other tutorials out there on Git, but Git is not the easiest tool to learn, and that tells me there’s a need for someone with my unassuming approach to write a tutorial about it.  I could have likely saved a fair bit of time and found the most unassuming Git tutorial on the internet and referred to it.  This is a reasonable compromise, but it only works if what you refer to is also geared toward your intended audience.

If I wanted to, I could have been much lazier and just left the tutorial off altogether and targeted a smaller audience–perhaps those already familiar with Git.  If I did, I would have stated clearly at the beginning whom I’m writing for, and it would have saved me a lot of time.  Anyone who wasn’t very familiar with Git that ignored that warning would be doing so at their own peril.  If I left that warning off, I am selfishly imposing on them the unexpected burden of doing significant research and self-learning in order for their investment in reading time to be worthwhile.

There is a wonderful article geared toward programmers, Solving Embarrassingly Obvious Problems In Erlang.  You don’t have to read that article, however, to get my point.  The author’s purpose is to promote maintainability of software code, or how understandable the code is to a programmer unfamiliar it.

A function is a named block of instructions, with inputs and an output.  Most computer programs are constructed of many functions.  A simple example is:

In this example, the function name is “add”, “a” and “b” are inputs, and the output is the sum.  A programmer can choose to write a very complex function, that does numerous things in order to compute the return value.  The author suggests breaking functions down into tiny functions, each named in a way that fully describes the purpose of the function.  When breaking up a function, he suggests first asking, for each line, “What’s going on here?” and then moving that line to a function with a name answering that question.  This results in the functions providing a form of documentation describing the code.  Understanding what a function does becomes very obvious for any future programmer maintaining the software.

A key point in this article is that answering the question “What’s going on here?” is noteasy.  It takes some thought to really break down what is being said into tiny, very maintainable components.   This process is necessary, however, because this information must be conveyed somehow.  If you do not cater toward the unfamiliar, than only the familiar will be able to maintain your code.  Otherwise, you should either acknowledge that your code cannot be changed without you and others intimately familiar with it being available, or, you are making it much more painful for future developers to be able to work with your code.  They’ll have to logically deduce why you do everything that you do, and they’ll have to often scour the internet and other resources to assist with this.  Some parts of your code may be outright impossible to understand without some explanation.

Aside from that obvious benefit, the “What am I really trying to say?” mentality increases your own understanding.  You must be knowledgeable to be explicit.  This article demonstrates this by showing that when you are explicit about what your code is doing, you are afforded the opportunity to optimize it due to your increased understanding.  Likewise, when catering an explanation to a less knowledgeable target audience, you are not only forced to truly master the subject matter, but you are also able to state it more clearly.

Another great thing about this article is that the author uses the Erlang programming language, but fully understands his audience may be completely unfamiliar with Erlang.  He makes a conscious choice to targetprogrammers of all languages, addressing the difficulty in understanding Erlang syntax early on, then he remains sensitive to that choice.

Erring on the side of unfamiliarity when assuming the knowledge level of your target audience is the safer practice, but try to not do more than you have to by encouraging the listeners to volunteer what they already know.  However, learn explicitly what they do know.  Sometimes an audience may generalize about an area of expertise, which can give you a false sense of security while explaining a concept.  Intersperse your explanation with confirmations of familiarity.  Reassure them that there’s nothing wrong with only being familiar with a portion of a topic and not everything.

In a presentation about “Khan Academy”, a web site with thousands of free online lectures, Salman Khan talks about the student analysis tools it.  They allow, among other things, a teacher to track the time a student spens on each problem throughout a homework assignment.  What they found was that seemingly slower students, when given assistance with a particular problem they were “stuck on”, would often catch up or even exceed the other students once they were given the necessary explanation they needed to surmount the obstacle.

This demonstrates the importance of not “skipping” elements of an explanation.  Explanations are naturally constructed in a hierarchy of understanding.  There is a set of fundamentals one must understand in order to master more advanced intermediate concepts required for them to comprehend your explanation.  The two sides to this are:

There are other common mistakes I find impedes the successful transference of information:

Knowledge sharing is at the core of much of our professional and personal encounters.  People possess various degrees of background knowledge, experiences, and cognitive abilities, and there are many potential impediments to understanding each and every bit of information.  Aside from attentiveness of the learner, the responsibility for successful transmission of information lies wholly with the one initially in possession of it.  By attempting to explain anything to anyone, you are engaging in a task that has potential benefit, but that also may result in disinterest in your subject matter, discouragement, or at the very least, a waste of time.  This may further evolve into a generalization of the target’s impression of interactions with you, and it is thus of social benefit for the transmissions to be frequently successful.  By consciously expending energy to practice empathy and non-assumption, articulating required background knowledge for their intended audience, one may greatly improve the quality of their interaction with others who have entrusted you with their time, attention, and perhaps curiosity.