How to explain technical information to someone with no technical knowledge

Last week as I was asked to describe what a JavaScript callback is to someone without any technical background. I thought about it for a few seconds and couldn’t think of a non-technical way to explain that a callback is a function that gets executed after another function has finished its execution, so then I was asked to explain a 500 error instead.

Explaining what a 500 status code is to someone with zero technical knowledge sounded more interesting and fun to me so this is what I remember saying…

A 500 status code is what you’ll get when a something has gone wrong on the web application’s server but the server doesn’t have any specific details.

Imagine a home with many doors, in this example, each door is a “web application” and the home is the “web server”, the place where all these doors are.

Now imagine that you open a door, and while the door does exist, there is nothing behind it, at this point the home will tell you that nothing specific exists behind the door so in web server language, that would be similar to a 404 status code which means “Not Found”.

What about the 500 status code? Well, if you attempt to open any other door and nothing works inside of it, the home will tell you that there’s something wrong with it, but not sure what it is. For example, there might be no lights or no water, but the home won’t tell you that, it just tells you that there’s something wrong and in web server language that’s usually what a 500 error means. Something is wrong with the web server or the app but it doesn’t know what it is.

If you can’t explain it simply, you don’t understand it well enough.
~ Albert Einstein.

By now you’ll probably already pulling your hair, and I understand, this is painful. My explanation or attempt to explain this to someone with zero technical knowledge wasn’t good enough, at least not in my opinion. But that isn’t the point of this, the point that I am trying to make is that it is very hard to explain something technical that is well understood by us and people that we work with, but not by anyone that isn’t technical and has zero knowledge about programming or web servers in the above example.

In my experience, having the ability to translate a technical problem or solution to a non-technical audience is key, it is something that you as a software engineer, for example, will need to do many times when communicating with business partners, customers, or anyone that isn’t a software engineer or has any technical knowledge.

How do we get better at this? Well, this is something that the more you do, the easier it gets, but it never stops being difficult. You might memorize a couple of examples where you can explain a couple of things, but with technology changing so rapidly it will be hard to have a template or an example of how to translate something technical onto something that anyone can understand.

The ability to tell a story is key to accomplish this, and without at least trying to get good at storytelling, your chances of confusing people and not being able to communicate something technical clearly are very low.

Also, be empathetic and patient. If you are trying to explain a technical concept be aware of who your audience is and tune your technical speak to their level. There might be times where you’ll replace the technical talk with something that your audience will understand, remember that your ultimate goal is to communicate and to do it clearly.

In conclusion, I learned something about myself and this blog post is the first step to improve it, I don’t think too much about how to improve my communication skills when trying to explain a technical concept, idea, or problem, to someone who doesn’t have the technical knowledge or experience with technical terms.

Here are some resources that I am using to help me with this subject:

Favorite New Visual Studio Code Features of 2018

Visual Studio is my favorite code editor, and the things I like the best about it is how light and extensible it is. Last week I posted some of my favorite extensions for this code editor, and today I want to show you some of the new features I like the most.

Visual Studio Code is updated frequently, and it is hard to keep up with all the new great stuff they keep adding to this editor. This is my attempt to help you discover some of the coolest features added to it so far this year, in my opinion of course.

I will update this post at the end of the year and include a summary of all the great features and advances of this mighty code editor.

The following features are just some of my favorites and the ones I use often. They are listed in the order they have been released so the most recent one and one of my favorites, the Grid Editor Layout is listed last as it was part of the June release.

Node debugging

Automatically attach debugger to Node.js subprocesses

For node-debug we’ve added a mechanism that tracks all subprocesses of a debuggee and tries to automatically attach to those processes that are launched in debug mode. This feature simplifies debugging of programs that fork or spawn Node.js processes like programs based on the “cluster” node module:

Auto Attach shown with Cluster Example

The feature is enabled by setting the launch config attribute autoAttachChildProcesses to true:

{
  "type": "node",
  "request": "launch",
  "name": "Cluster",
  "program": "${workspaceFolder}/cluster.js",
  "autoAttachChildProcesses": true
}

Auto-imports based on filename

Auto-imports for JavaScript and TypeScript now support importing default exported objects based on filename:

importing a default exported object by filename

Copy/Paste files across windows

We now allow you to copy and paste files between two VS Code File Explorers in different instances. This works for single or multi-selection of files as well as folders.

Copy Paste across Windows

Split terminals (My personal favorite!)

The Integrated Terminal can now be split such that multiple are visible at once, which can enable much easier management of terminals when you need a watch and a run command for example:

Split terminals

Splitting can be done by clicking the split button in the panel, through the context menu or the command Ctrl+\.

Focus can be moved between split terminals using Alt+Right and Alt+Left. The active pane can be resized using the keyboard with:

  • Terminal: Resize Pane Downunassigned
  • Terminal: Resize Pane Upunassigned
  • Terminal: Resize Pane Leftunassigned
  • Terminal: Resize Pane Rightunassigned

Syntax aware folding

Folding ranges in HTML, JSON, Markdown, CSS, LESS and SCSS are now, by default, computed based on the language’s syntax and no longer rely on well-formed indentation.

Syntax folding

Support for TypeScript and JavaScript is also available, and can be enabled by the setting "typescript.experimental.syntaxFolding": true.

If you prefer to switch back to indentation based folding for one (or all) of the languages above, use:

  "[html]": {
    "editor.foldingStrategy": "indentation"
  },

The extension API now supports adding related information to diagnostics and this is shown in all places where diagnostics are shown: on hover, the error Peek window, and Problems Panel.

In the example below, you can see related information pointing out the first location where a twice assigned variable was used:

Related Diagnostics Information

Column selection using middle mouse button

In VS Code, column (box) selection can be added by holding Shift and Alt and then using the left mouse button. Now the middle mouse button can also be used to create a column selection:

Editor column selection

Note: When setting editor.multiCursorModifier to ctrlCmd, the modifiers are Shift and Ctrl on Windows and Shift and Cmd on macOS.

Highlight unused variables and imports

Unused variables, parameters, and imports are now greyed out in JavaScript and TypeScript:

Many greyed out unused variables

Use a Quick Fix to remove them and clean up your code automatically:

Quick fix all action

Grid editor layout

You can now arrange editors both vertically and horizontally and have more than 3 editors side by side:

Grid Editor Layout

To support flexible layouts, you can create empty editor groups. By default, closing the last editor of an editor group will also close the group itself, but you can change this behavior with the new setting workbench.editor.closeEmptyGroups: false.

Grid Empty

There are a predefined set of editor layouts in the new View > Editor Layout menu:

Grid Editor Layout Menu

Editors that open to the side (for example by clicking the editor toolbar Split Editor action) will by default open to the right hand side of the active editor. If you prefer to open editors below the active one, configure the new setting workbench.editor.openSideBySideDirection: down.

Like I said above, it’s hard to keep up with all the great features being released so often, so please feel free to leave a comment with your favorite feature added this year or something that you’d hope they will add in the near future.

For the full list of features released so far this year, click here.

Happy Coding!

Favorite Visual Studio Code Extensions of 2018

Visual Code is a fantastic code editor, but what really makes it powerful are the extensions available for it. In this post, I share some of my favorite VS Code extensions while using VS Code to develop web applications.

  • WakaTime – Metrics, insights, and time tracking automatically generated from your programming activity.
  • GitLens – GitLens supercharges the Git capabilities built into Visual Studio Code. It helps you to visualize code authorship at a glance via Git blame annotations and code lens, seamlessly navigate and explore Git repositories, gain valuable insights via powerful comparison commands, and so much more.
  • REST Client – REST Client allows you to send HTTP request and view the response in Visual Studio Code directly.
  • Npm Intellisense – Visual Studio Code plugin that autocompletes npm modules in import statements.
  • Code Spell Checker – A basic spell checker that works well with camelCase code.The goal of this spell checker is to help with catching common spelling errors while keeping the number of false positives low.
  • Azure Storage – The Azure Storage extension for VS Code lets you deploy static websites and browse Azure Blob Containers, File Shares, Tables, and Queues. Follow this tutorial to deploy your web apps to Azure Storage from VS Code.
  • Night Owl – A VS Code theme for the night owls out there. Works well in the daytime, too, but this theme is fine-tuned for those of us who like to code late into the night.
  • Project Manager – It helps you to easily access your projects, no matter where they are located. Don’t miss that important projects anymore. You can define your own Favorite projects, or choose for auto-detect VSCode projects, GitMercurial and SVN repositories.
  • Todo Tree – This extension quickly searches (using ripgrep) your workspace for comment tags like TODO and FIXME, and displays them in a tree view in the explorer pane. Clicking a TODO within the tree will open the file and put the cursor on the line containing the TODO.
  • Turbo Console Log – This extension make debugging much easier by automating the operation of writing meaningful log messages.

Do you know of any cool and useful VS Code extensions? Please share them in the comments.

Happy Coding!