You've been asked to give a dApp workshop. Now what?

Introduction

This article is meant to serve as a guide for those who are leading, or would like to lead, a Status workshop. In this guide, “you” are the workshop presenter.

The application of this guide is specifically set up for dApp workshops using Embark, however various elements of the guide can be extrapolated as needed to suit other workshop applications, especially the Audience Engagement and Giving the workshop sections.

The format of this guide is based on audience members coding along with the presenter in the end goal of making a fully functional dApp. It requires the presenter to engage the audience through the entire workshop as audience members follow along and add code in their own codebase. This is exactly how the DTwitter dApp created for DappCon 2018 was geared and, in general, this guide is derived from that particular experience.

As a side note, there are many alternative workshop formats to code-along. One format in particular that may have a way of achieving a similar effect of audience engagement is to present a challenge to the audience, for example, “given the cloned codebase, figure out a way to achieve end goal X”. In that case, there will be less presenter talking and more hands-on helping individuals. And from what I have seen, this invites a lot more audience frustration. Another challenge with this format is handling internet blackout.

Preparation

To prepare for the workshop event, we should first have a fully-functioning, tested, and documented dApp.

First, we need a complete dApp

The dApp should have one (or more) smart contracts, unit tests for the contract(s), and code to run the dApp. Alternatively, it could include other decentralised technologies like decentralised communication (Whisper) and/or decentralised storage (like IPFS or Swarm).

Function

Before anything else can be done, it’s necessary to have a fully-functioning dApp. The fully-functioning dApp codebase will become the master branch and will serve as reference information for those following the workshop and/or for those who missed the workshop and would like to follow the workshop material as a tutorial later on.

Documentation

The fully-functioning dApp should be completely commented in “tutorial style” so that anyone who is attempting to learn from the workshop can read the comments and gain insight as to what is happening in the code.

End-user testing

The dApp should also be tested on several different machine configurations to weed out any environment bugs. This is exactly what will happen in the live workshop, so it’s best to get this out of the way early.

Now, let’s make the code “fill in the blank”

Once the dApp is fully complete, create a start-here branch off master. This will serve as the branch that your workshop hackers should clone.

Then, remove lines of code that can be easily explained and written out during a live demo. One comment per line of code is usually good because it serves as a placeholder/reminder during the workshop (for you, the presenter) and cues participants where code needs to be added.

Commit your changes to the start-here branch. You should have a fully working version on master and a workshop-ready version on start-here.

Instructions

The instructions will be a guide for all workshop attendees and/or anyone following the code as a tutorial. In addition, the instructions can serve as notes that can be used as you present the workshop.

The instructions should be markdown files committed to the master branch in a root-level instructions folder. The instructions should be ordered and organised in a way that is easy to follow, i.e. give each instruction page a number prefix (for order) and a name. For example, the DTwitter workshop dApp instruction structure looks like the following:
Instructions-structure
The instructions should be written in “tutorial style” and should include an overview of the workshop and the dApp, installation requirements for the workshop, and steps to execute during the workshop.

Overview

This should include an overview of the workshop you are going to be presenting. For example,

“Today we are going to build a decentralised twitter dApp using Embark.”

The end goal of the completed dApp should also be included. For example,

“Our DTwitter dApp will be able to create and edit users stored in our contract, and send tweets via the same contract, while receiving them in our dApp in real time. Any profile photos uploaded will be stored in IPFS.”

Installation requirements

Any pre-requirements (e.g. install Node LTS, MetaMask) that are needed on the hacker's machine to successfully complete the workshop should be documented in the instructions. Specific version of each tool should be explicitly written. Ideally, the pre-requirements should be communicated to the participants before the workshop starts. This could be in the form of asking the conference organisers to list the requirements for the participants on the schedule/description of the workshop.

Workshop steps

The workshop steps should include the exact actions that need to be executed by participants during the workshop. These instructions should be verbose and should include directly the code that needs to be added to the start-here branch to get the dApp in to a working state. The code snippets here will essentially be those that were removed from the Now, let’s make the code “fill in the blank” section. Additionally, these steps will serve as your notes during the workshop in case you forget which code needs to be written in which section (this can and probably will happen in the span of a 1.5-2hr workshop).

The steps should include code information on how to complete the code for the:

Smart contracts
Unit tests (TDD)
Finally, the dApp (js) code itself

Examples of these steps can be found in the DTwitter workshop dApp instructions.

Print your notes!

Print everything from the “Instructions” section. Notes can serve as a reminder if you forget which bit of code to write. This will help you keep the “flow” during the workshop (as well as during practice). The not-so-nice alternative is to swap applications, while presenting, to check your notes, which can be disruptive for those following along.

If you don’t have access to a printer, ask a colleague, ask the hotel reception, or ask someone at the conference.

Prepare for the case of internet blackout

It happens. In fact, it happened at DappCon 2018. The wifi was “working” but the effective speed was 0Mbps and not a single person (including me) was able to use it. Therefore, it is essential to have an internet blackout plan.

Luckily for me, during DappCon, I had a 3G connection on my phone that I could use for cloning the repo and npm installing dependencies. None of the participants could code along with me but at least I was able to continue with the workshop as planned. And because no one could code along, audience engagement suddenly became much more important.

A suggestion for a plan is that you might have any one-time internet dependent fetches done prior to starting the workshop. For example, the start-here branch could already be locally cloned, npm installed, and an embak run dry-run done (to allow the library manager to download libraries).

Also, simulate the internet blackout scenario in one of your practice runs. Each dApp will have unique internet necessities, so the best way to plan for this is to try practising your workshop with no internet.

Practice

Generally, it’s a good idea to do a minimum of three dry-runs with colleagues. At the end of each dry-run, get feedback from each colleague, take notes on the feedback, and use it to improve your next dry-run.

If something breaks for you or one of the participants during the dry run, take a note of it, and try to fix the bug before the workshop by way of a patch if possible. If the code change is going to be too large, don’t spend your time trying to fix it and possibly not having a stable codebase, instead jot some notes on the cause of the issue. If this bug occurs during the workshop, point it out to everyone there, explain the cause, that it’s a known issue, and that it is currently being addressed. It’s much better to expose the bug (that’s in plain sight to participants) than to get caught out and try to cover it up. Also, remember that generally every participant is a developer, so they know what it’s like to deal with bugs!

Giving the workshop

This section is all about the delivery of the workshop (and should also be followed during your practice dry-runs).

Pre-start

Before you get up to the front of the room, you should have an IDE open with a working copy of the code (ie master branch checked out). This serves as a “backup” copy for when things go south during the workshop and you can’t figure out why.

Connect to a VPN if possible to mitigate hacking attempts.

Figure out how to connect to ethernet if it’s available, instead of the wifi. For MacBook users, this usually requires a dongle, and generally the technician for the workshop room should have some available for you. If not, wifi it is 🤞.

Start

Presenting the workshop will start with a “hello” to the participants, and introduction to who you are and what you are presenting, and it’s courteous to thank the conference organisers for having you (if applicable). The introduction to the workshop should be a high-level overview about what is going to happen in the workshop. For example,

“Today, we are going to build a decentralised Twitter dApp using Embark by Status. We will create a contract to create and edit user profiles, check if users exists, and store tweets. We will use test driven development to unit test our smart contract. And finally, we utilise the APIs of Embark to interact with our smart contract and with IPFS to store and retrieve our profile picture. This is meant to be a code-along workshop - so we will be coding together!”

Pretty much from there, you will follow along with talking through your instructions. In the case of the DTwitter workshop, the instructions include a section on What is Embark?, so naturally, it was one of the first things covered in the workshop. However, if you need to have the participants perform an installation, which everyone will have to try do simultaneously (network speed might be an issue here?), this will require a bit of waiting. So, you could ask everyone to start the installation steps first, then while waiting for installation to complete, explain to them what Embark is about.

First run

Once the start-here branch is cloned, run Embark on the dApp (cd path/to/dapp && embark run) and explain to the audience everything that is happening, and everything that will happen.

Coding

This will be the bulk of the workshop, and should be thoroughly covered in your instructions.

Troubleshooting during the workshop

When coding the dApp and it doesn’t go as expected (e.g. there’s a unknown error), follow these steps:

Try to debug it live. Show the hackers how you work, they love to see it and it’s a valuable learning experience. Remember to explain things as you go.
Ask the audience for suggestions on how to fix the error and give them time to respond.
If all else fails, or the debugging is taking more than 2 or 3 minutes, bail, and overwrite your changed code with the working code from the master branch (remember - you have an IDE open with the working copy already). Explain to the audience what you are doing, and that you can figure out what went sour by doing a diff on your current code vs your working code after the workshop has completed.

Audience engagement

Keeping the audience engaged is very tricky with this kind of content. Be proud and show the audience how excited you are about your work! You can think of it as watching a sporting event where the announcers are just listing play-by-play what is happening. But instead, if they show some passion about how amazing a play was or how talented a player is or a bit of backstory or stats, that enthusiasm draws in the audience.

Tips for engagement

Find a buddy

Find a buddy (or buddies) in the audience and learn their name(s). Use their name(s) and engage with them directly throughout the presentation. For example,

when demonstrating how to create a new user in the DTwitter dApp, use “igoriscool” when Igor is your audience buddy.

Ask questions

Ask the audience questions and wait for a response. A few examples are listed below.

“Any questions so far?”
“Is this making sense?” (And look in the audience for puzzled faces)
Leading questions like “call is for… And send is for…”. Any leading questions should have been clearly explained a few times as if to establish a pattern prior to engaging the audience, so that they have a chance of answering the leading question.

Wait for these answers and if no one responds ask why (maybe the question was not clear), explain the answer, then continue.

Be the audience

When presenting, put yourself in the shoes of the audience. You have been to workshops and conferences before, so you know what it’s like to be an audiencen member. Try to be the presenter you wanted when you were sitting in the audience. While attending other workshops, ask yourself as an audience member:

What are they doing well?
What could they do better?
Were there clear goals for the workshop?
Did we achieve those goals, and if not, what was missing?

Pre-workshop checklist

Completed dApp (working, documented, and tested)
3+ practice dry runs complete
Internet blackout plan ready
Notes printed
Laptop charger packed
Ethernet dongle packed or organised ahead of time
IDE with master branch loaded and ready

Future considerations

Here are a few things I’m currently researching, to help make workshopping an altogether more enjoyable experience for the presenter and for the hackers.

CodeSandbox

CodeSandbox provides a hot-reloadable and sharable environment with the ability for the entire room to live code together. This way, when the presenter types, not only will their screen be shown on the projector, but attendees who have loaded the CodeSandbox app will see the code change on their screen too. It’s kind of like Google Docs for coding.

I can see this being an immense tool for effective learning. This will only be possible once EmbarkJS library is released separately (and can be imported in to CodeSandbox). Each hacker will still need to run their own node (via embark run), and even then it might not be entirely possible as the CodeSandbox environment might not be able to access “http://localhost:8545”. More to come...

Eric Mastro