We love to teach here at Big Nerd Ranch, but we don’t just teach classes. We write blog posts and speak at conferences, too. For all of these activities, we inevitably have code we want to share. Sometimes the best way for us to do that is via a demo app.

This post describes some best practices we’ve come up with (rather informally) about crafting the most helpful demo app we can.

Empathize with Your Audience

Empathy is at the root of all of these tips. When we teach, we make an effort to put ourselves in our students’ shoes. We remember what it’s like to learn something new, especially when the material is presented as a working example. We remember which demos have helped us. We also remember the ways that some demos actually made the material harder to learn.

Keep It Simple, Stupid

In our demos, we focus on a single topic. We cover a lot of ground when we teach, so breaking a big idea into smaller parts is necessary.

For example, if we are demonstrating a new feature in Android or iOS, we present just that one topic. We don’t write demo apps that showcase the newest UI elements in Material design and introduce RecyclerView and discuss some new feature of RxJava. If we want to share knowledge about these disparate topics, we create a demo app for each.

Underestimate Your Audience

Not all students are at the same skill level. While one student may have 10 years of development experience, another may be only a year in.

When it comes to creating a demo app, we try to err on the side of underestimating our audience’s experience and choose to present as clearly as possible. Our goal is to help a range of skilled developers to benefit from our demos.

Rely on Native Solutions for the Non-Essentials

Our brains do a good job of picking out new things we don’t understand and glossing over things that look familiar. This is especially true when reading code.

If an instructor is demonstrating some new topic in a bootcamp, we want the code bits that relate to that topic to stand out. One way to do this is to make all of the non-essential parts “disappear” by relying on those coding solutions that are most familiar.

Let’s say we’re demonstrating some new feature in RxJava, and we build a dummy fragment and view to visualize the results. If we throw in an additional advanced approach, such as applying Butterknife annotations to the widgets, it’s only going to clutter the relevant RxJava details. Anyone who isn’t familiar with Butterknife is going to see those annotations and get distracted by wondering, “What is this? What does it have to do with RxJava?”

Instead of throwing in a bunch of extraneous information, we stick to good old-fashioned findViewById(). This way, students will see findViewById(), recognize it and then ignore it. They can then continue scanning for code new to them.

Document Your Anti-Patterns

Your entire demo app can’t be perfect. You will inevitably have to cut corners to set up some framework that is ancillary to the topic you’re demonstrating. A demo app is different from a production app; cutting corners is OK. Whenever you save time by cutting those corners or doing something you really shouldn’t, make sure you point it out. If you fail to do so, you risk two things:

• More experienced developers will see your nasty code, and you will lose credibility with them. They will wonder about the value of the important parts of your demo. If you did a hacky job of setting up a model store to provide some dummy backing data, how good could your solution to the real problem actually be? Let those experienced audience members know that you recognize that you are cutting corners.

• You don’t want your hacky solution in a demo to become a real solution in a novice’s production code. Novices might inspect your code, see that it works technically and then implement it as part of a project. We try to be good teachers and make sure that students aren’t picking up any bad habits.

Readme > Javadoc

The documentation techniques we use for a production apps and libraries don’t have the same audience as a demo app. GitHub is great at formatting a README.md file for easy viewing. This acts as a great table of contents for our demos. It gives us a chance to provide the audience with a high-level overview of what we are trying to showcase. Including screenshots, animated gifs and step-by-step setup instructions can really add value. Use them liberally.

Javadoc is great when you know what you’re looking for. They are terrible, though, for someone learning something new. You aren’t building documentation for an API that developers will use every day. Tailoring your documentation to less-experienced developers is incredibly helpful.

Comment—A Lot!

In production projects, there is a fine line between too much and too little commenting in code. In production, you run the risk of your comments becoming out of sync with the code as your team refactors. However, a demo project is usualy updated so infrequently that this isn’t really a problem. Remember that you are explaining something new to somebody. Walking the student through code, line by line, can be really helpful.

In production situations, developers have so much more context when it comes to reading and understanding code. They may already have a high-level overview of what the code is supposed to do. They may have heard other team members talking about the problems the code is trying to solve. The team may have already agreed on some design patterns that this code relies on. In-production comments serve a different purpose. They provide simple, high-level guidance.

For a developer seeing a demo project for the first time, none of these bits help them build a context about the workings of the code. They are both new to the project and new to the technique or library being showcased, so it can be really helpful to use lots of comments to make the logic and flow more obvious.

Put Your Demo Out There

If your demo is best understood by actually interacting with it, rather than just looking at code, do your audience a favor and put your app out there. Build the project and put it on the Google Play store or Apple Store, then link to it in your README.

Because students may not take the time to clone your repo, import it onto an IDE, then build and deploy it to a local device, you should do whatever you can to help your audience start interacting with your app as quickly as possible.

These are just some techniques we use to write great demo apps. Let us know what you like to see in a good demo or share a link to your favorite demo app.