Made by
Made by
Developer Relations Lead
Directus
DevRelCon Prague 2022
As developers, we want to showcase our products in the best light, providing beautiful and complete demos for others to learn from. But with completeness can come unnecessary additions and opinions which don’t support developers in extracting the knowledge they need to be successful.
In this talk from DevRelCon Prague, Kevin discusses how to understand the user needs for your demos, and how to build learning experiences that both highlight core features and make them easy for your users to apply. You’ll leave with a framework for designing fantastic and impactful demos.
Key Takeaways
Kevin: Thank you.
You know that it is pretty effective. I feel properly hyped up. Yes, everyone who runs events, do that. It might feel awkward on that side, but it really works this side. Hello there. My name is Kevin Lewis. I run developer relations at Directus, an open source data platform that sits alongside your database, introspects your database schema, and spits out APIs and a no-code app to interact with it. I’m also director of You Got This, where we run community events and maintain a free content library entirely focused on building people’s core skills. I previously worked at Deepgram, Orbit and Vonage among others. My DevRel specialisms are developer education and events. So if you want to come chat to me about that in any break, I’m more than open to talking about that. You can find me as @_phzn both on Twitter and on Mastodon using @lws.io.
You can find a summary of this talk, so you don’t necessarily need to take notes. If you want to, I won’t stop you, but if you want a summary of this talk, I’ve popped it all on my website @lws.io. Now, there it is. So I wanted to take a moment just to situate this talk, because the word demos can mean many things. Demos can be used to describe live sessions that we give to developers, perhaps at events or online. In fact, Naomi Pentrel did a fantastic talk about building convincing demos at last year’s DevRelCon Online. Demos can also be used to describe the experiences that developers have, perhaps at a booth or online, whether that is an educational or novel fun experience. I touched on this in my DevRelCon talk last year.
Finally, in the subject for today, we are going to talk about self-serve technical and code demos that developers can use to do multiple things. We’ll talk about that in a moment. I’ll also be referring to Philippe Ozil’s blog post on developerrelations.com on building great sample apps. So this is what we’re going to cover today. We’re going to start by talking about the different user needs and motivations of developers and companies building and using these technical self-serve code demos. Then we’ll talk a bit about kitchen sync demos, what that means ,when they’re appropriate, and perhaps when they don’t work as well. I’ll introduce you to my idea of atomic demos as a way of deciding what needs to be built. Finally, we’ll move on to some questions you can ask when getting started in your own organisations. So let’s start by talking about the user motivations.
I propose that there are three core motivations for businesses and developers using these kinds of demos. They are not mutually exclusive, but they are as follows: Firstly, inspiration. Inspirational demos demonstrate your features in interesting, fun or novel ways to draw in new and existing users. They’re really powerful for discovery and marketing, and sometimes have the privilege of doing rounds on social media. An example of something like this is using Ablead to create a fun multiplayer game that looks really great and people have lots of fun using. Gets people in the door. Next is evaluation. An evaluation demo supports your company or organisation in helping people decide to actually jump in and use your technology, or win comparisons with competitors. Now these sometimes overlap with the business needs of inspirational demos, but it isn’t always the case. These specifically support sales activity. For example, showing how directors can be used as a fully featured headless CMS with all of the features under the hood in order to convince someone to go ahead and use it.
Finally, education. Now educational demos show developers how to implement your product features in the context of their own projects. They’re really powerful for developers’ learning. They’re useful for solutions engineers and also for success and support staff, or functions like us. So for example, implementing a green screen replacement with the Vonage video API. So in summary, these are the three main motivations I find that businesses and developers have when they’re approaching your demos. Again, not mutually exclusive, but good as a starting point for the next bit, which is to talk about the kitchen sink. Now, everything but the kitchen sink – this has nothing to do with Elon, by the way, I wrote this talk title well before this series of events unfolded. Everything but the kitchen sink is a saying that means everything you can think of.
In the context of demos, it means one which showcases all or many of the features all at once, even if that might not be realistic. Now, kitchen sink demos are often more feature complete, more attention paid to finish and polish. They’re often use case driven and may even co-situate your product with some other complementing product from another company. Finally, they’re more likely to be maintained and kept up to date to remain functional. While not always true, inspirational and evaluation demos more closely align to this concept of a kitchen sink demo, perhaps more so than educational demos. Now, here is an example of a self-proclaimed kitchen sink demo. It uses every conceivable feature in the Spotify apps API at the time it was developed, which was a very long time ago. So I don’t how much of this still exists, but that’s a lot of features and it’s wholly unrealistic that a single application built with this API is likely to use all of that functionality at once, but it’s here in the kitchen sync demo.
I wanted to also just do a quick aside and talk about this concept of business oriented and recipe apps. In Philippe’s blog post on developerrelations.com., he talks about different kinds of sample apps, which I will call demos for clarity, so we are using the same word. He describes two main kinds of demos. Firstly, business oriented demos, which tell some kind of story tied to customer use cases, and recipe demos, which contain collections of small code snippets and code patterns that show how you would implement small discrete pieces of functionality. I wanted to raise this, not because it’s actually a very interesting read on the blog, but also because perhaps business oriented is a bit more of an appropriate way to talk about these more complex demos than kitchen sink, when you go back to your orgs and talk about them. They’re kind of one in the same in the way that they are being described.
Make no mistake, developers learn in different ways. Some developers can jump straight into a complex code base and extract value. Some can read source code and understand what’s going on, but this isn’t a universal experience. So I want to talk about some challenges with these kitchen sink demos, and then we’ll move into talking about perhaps an alternate approach or a complimenting approach that you can also undertake. So, Philippe makes a great point in his post that these more complex demos expose best practice which goes beyond just writing code, whether that’s software lifecycle management, CI workflows, packaging and release management and so on. While he presents this as useful, I don’t think this is true in all cases because the byproduct is you’re having to teach a lot more than just your product, which might lead to confusion or a challenge for developers using this demo in understanding what your product is and the situational kind of environmental codes that surround it.
Next, believe it or not, all developers are opinionated in how they write code. We are no different. These sets of opinions will bleed into how we write sample demos, generally moreso, the bigger and more complex they get. If a developer is not familiar with our choices and patterns, it may then become difficult to understand what’s going on. Using a front end example. If you are familiar with Tailwind CSS and you use Tailwind in your little sample, fantastic. If you’re familiar with Tailwind though, and imagine you don’t and you jump into that project, ‘what the heck is going on? There’s so much going on in this code base, and now I’m really not sure what I need to understand in order to progress’. Demos intertwined with overly specific use cases might also make it difficult to extract value for other, perhaps even similar, use cases.
So when learning from these demos, developers might, even if it’s just a mental block, feel that they’re either locked into your very specific example or be able to extract nothing at all from your demo, even if technically they are similar or the same. There are also challenges and complex demos as it pertains to us as developer relations practitioners. While it may sound obvious, they take way longer to build and they have a much bigger burden of maintenance. We’re reaching the end of this section now, but I wanted to talk a bit about the uncanny valley. Can I see a show of hands of those of you who are familiar with this term? Okay. For those of you who aren’t, the uncanny valley describes the expectation and emotional response people have towards humanoid robots in relation to their realism. Once they reach a level of realism, they stop being cute and start being creepy.
While it’s not quite the same, the more realistic your demo is, the higher expectations developers will have of completeness, future completeness and polish. In some ways, sometimes doing more work to build a better demo might actually lead to more disappointment in the eyes of the people using it. Finally, the more code in the project isn’t related to your product, the more explainers and education you need to do to explain them. Despite what many may think or hope, it is not always our job to teach people the prerequisite skills required to come to our technology. It’s a stretch goal. It’s not THE goal. The goal is to teach people how to work with our technology. So you don’t necessarily want to muddy your demos with a whole bunch of additional education requirements. So here’s a summary of the challenges with kitchen sink demos.
None are insurmountable, but they do take effort and time to overcome, especially as you start to compound them and have to handle multiple at the same time. So, we’ll talk about how to build smaller demos in a moment, but I wanted to just open with why I think they’re an excellent addition to your repertoire of educational content. It comes down to basically solving the challenges I just mentioned. Developers can more easily lift and drop code from your demos into their projects with greater comprehension and without the need to understand or care about a specific use case. On our side, as the people building them, they take less time to build, there’s less maintenance requirements and, and we’ll talk about this later, they can be used more easily as reference material later on when trying to support and educate developers. So, let’s talk about building smaller demos.
I want to introduce you to Atomic Design. This is a methodology for creating interface design systems created by Brad Frost. There’s an excellent book about it. While we’re not building interfaces, there’s a lot to be gained with this kind of mental model when building educational material. We’re going to start with atoms. Atoms are foundational building blocks. They demonstrate the most basic functionality and features that your product offers in isolation. In the context of demos, we may call these getting started or X with Y, single feature, single language framework or environment, whatever is kind of applicable to your product. You might end up having a lot of these in the end, but each one of these demos will make it clear the impact of a specific feature that you offer. To use a tangible example, how to send an SMS in no JS with Infobip, not necessarily what my slides originally said, but we’re going to say Infobip.
It is a specific feature. It is a specific environment language. So it’s really clear what you’re doing, there’s no more cruft around it. Now, in atomic design molecules are relatively simple groups of features that work together as a unit. They still generally are independent of use case, but they start to demonstrate complimenting offerings you have, or perhaps they co-situate your features with complimentary third party platforms or partners. An example here: Using Deepgram speech recognition API and combining three of their features – speaker detection, paragraphing and punctuation – for a human readable transcript. Doesn’t talk about the use case, but it’s talking about how you combine these various units of features together. Moving on, organisms are more elaborate and they start to provide context for features being presented together. This is a very typical demo type for DevRel. We start to build meaningful functionality which may at this point introduce some context or use case.
For example, while a molecule might be on trigger sending an email. An organism might be sending an email on an abandoned cart. Now you also need to build logic for the abandoned cart feature in order for this to work, but it’s now more use case, contextually placed. Now atomic design kind of breaks the chemistry analogy here, so, so will we. Templates are what we would call kitchen sinks or business oriented demos. They bring together all these discrete pieces of functionality into a more fully featured demo. Expanding the e-commerce example, this would be providing a fully featured e-commerce demo as a template. As you can start to imagine as we’re going down this path here, there’s a much higher degree of complexity that’s now being reached at this point. In this template, there are several organisms, each comprising several molecules and finally down to atoms.
That’s not to mention that with more complex projects, there’s more bootstrapping and environmental code required in order to make them work. To use another example, DocuSign, the e-signin platform, has a set of these kind of template projects. They have one called My Government. I’m going to read you what it says as the description for this and hopefully you’ll start to see this. My Government showcases how a government agency can leverage DocuSign features such as embedded and remote signing, conditional recipients, branding, document visibility, payment, identity verification and more, because there’s more apparently. But you can start to imagine the sheer complexity of these projects, perhaps very useful, but they take a lot more to build. Finally, pages. Now pages are specific implementations of projects. So you might build a template for a content page and then you would have the implementations of that template.
In the context of demos, this doesn’t really exist as much. This is where we’re starting to talk about user specific implementations. It’s a developer taking your template and applying it. This is less about demos and more about supporting an actual developer building with that demo. So, to summarise this kind of atomic design as it pertains to demos, atoms show a single feature in a single language framework or environment. Molecules start to combine complementing features and technologies. Organisms add a little bit more context and the code which backs that up. Templates are more fully featured sample demos. Pages are user led implementations, not demos, but I wanted to include it because pages is a concept in atomic design. I’m a completionist, so we wanted to add that one on there at the end. One of the great things is that when you start to build code samples and demos in this way, you can reference the lower level demos when teaching rather than starting from scratch each time.
You don’t need to teach people how to send an SMS in no-js. You can refer to that piece of content that exists and that goes all the way up the chain. This also supports the maintainability up the chain, because when things change, you don’t have to change it in as many places, which in turn gives your content and your demos a longer shelf life. So, moving into this last part, we’re gonna talk about how you can get started with this. Now I’m gonna refer to Naomi’s amazing talk on building convincing live demos, where she presents a solid checklist for getting started. While they’re not all applicable, we’re going to take what she’s built and we’re going to adapt it. So props to Naomi for this bit. First thing we’re going to do is gather requirements because demos are projects and every project needs a set of requirements before we start, right?
So you’re going to ask some questions of everyone involved. Firstly, what specifically are you trying to demonstrate? What specific list of features are and aren’t we demonstrating with this demo? What is the business and user goal? It can be any of inspiring, evaluating or educating or, perhaps multiple. Who is the audience member? What industry are they in? Do they have a specific language or framework affinity? What’s their tech stack, their experience? Finally, who are the internal stakeholders who you need to work with in order to design and deliver and maintain this demo? As part of this gathering of requirements, you also need to agree upfront with all stakeholders whether this demo is going to be an atom, a molecule, an organism, or a template. An agreeing upfront means you can protect yourself from future scope creep and know when you are done and it’s actually ready to make it out the door.
You also want to understand straight away who’s going to maintain this. Every demo has maintenance requirements and it should be agreed upfront who this work belongs with and that that capacity is carved out at the start. The more complex the demo, the more regularly you’ll need to go back to it and the more time you’ll need to spend each time. These questions are absolutely critical for making sure that demos actually make it out the door, are useful and are maintained. So finally, some closing thoughts. Firstly, don’t compromise the goals of DevRel when building demos. Developer relations overlap so many other teams’ interests, so you have to make sure to gather requirements and agree the scope of a demo before starting and make sure that that is written down and we all agree. We so often give our time and energy to other teams’ goals, we sometimes jeopardise our own.
So, to give you a tangible example here. You may agree to build a demo in the style of a molecule and someone in another team, for example, sales or marketing – I’m specifically using these examples because it is generally in the interest of sales and marketing functions to have more future complete and polished demos – they may push you to add those features or polish, which then make the demo hard to use as an educational resource. So be aware of this. Push back with your original statement of work. It doesn’t mean you can’t have two demos that are similar, but at various levels of completion. Perfectionism, it can be a distraction. There is always something more to build, there is always some more polish to add, but you have to ask yourself, is this going to help me teach developers how to use the thing?
If your goal is to educate. If the answer is no, you shouldn’t be adding that polish, you shouldn’t be adding that line of code, you shouldn’t be adding those attributes, you shouldn’t be adding that styling because it isn’t helping the end goal. While they might be straight more straightforward, these kind of lower level demos, these atoms and these molecules in particular, are really important to keep up to date because in theory, the lower level they are, the more they are referenced elsewhere. Finally, while this talk is specifically about building demos, this approach influences how I create other educational material as well. Hopefully you have got some value out of it and you can go and make some wicked small demos. Thank you very much.
Presenter: Thank you Kevin. How about questions guys?
Audience member 1: What’s the relationship or how do you balance discoverability and making sure that you have enough code samples that have coverage and discoverability with duplication?
Kevin: With duplication? So, this is a really tough one. Every time you go up the stack, every time you build complexity, you are also including code further down. This is tricky because not every demo generally exists as just a sample app. It comes with the associated educational material, explainers front page that explains what’s actually going on. You simply can not stop the duplication of code because again, as you go up the stack, that code that sends that email needs to exist in it. You don’t necessarily need to go quite as indepth in your explainers. Maybe that wasn’t clear, so I’m really thankful you asked this question. Demos generally don’t stand alone. They come with some form of additional educational material, whether that is simply a read me that explains what’s going on, a blog post, a use case page on your website, and that’s where you can avoid the duplication. Fantastic question there.
Audience member 2: That was brilliant, thank you. You mentioned the atomic design book and you refer to a talk by Naomi on building convincing demos. Are links to those on your webpage?
Kevin: Yes. Thank you. Am I free to go? Not quite.
Audience member 3: I was just wondering how many of these small demos kitchen sink demos have you made over the course of time?
Kevin: Depends where I’ve been. When I get into an organisation, part of it is assessing what already exists and what needs to exist. Some companies that I’ve joined, a lot of these lower level, kind of more atomic demos, they’ve been created. Vonage, the concept X with Y was one we spoke about a lot where we’ll go with the core functionality in any of six or seven languages, and most of the coverage was already there, didn’t need to do that. I’m mostly focused on that kind of middle of the road. I’ve built remarkably few of these more template demos because they are so time intensive and not everyone finds value in them. I think people find value going one level down. I’ve built quite a few demos at this point and that’s quite typical when you’re building a blog post. Even if it’s a fun little project, chances are it’s starting to venture into this world of being a more ‘organism-ic’ demo. At some companies though, that foundation has not been laid adequately and you have to focus there otherwise you’re building on top of it and you are lacking the getting started guides that people need, free of use case, free of combination with other features.
Audience member 4: When you do atomic demos, how do you ensure findability with the overlapping tagging? Your tags start overlapping and your small demos may compete with each other. How do you ensure findability if people don’t find your demos within these contacts, but they look for it on YouTube?
Kevin: To be fair, not all of these demos need to be front and centre in the way they’re presented. Some of them can exist in various guises in various ways with various degrees of effort placed on how much you are going to make them findable. Some exist purely as reference material. This is going to help support staff when people come in with a problem, they can send people to this article.
The question was, at what point along this spectrum of atomic design are you optimising for findability? I don’t know! I could stand here and I could schpiel off the top of my head, and I’d be interested in talking to people about this in the break. But the real answer is, I don’t know. I think every project has different demands of information architecture and how people navigate documentation and blogs and tutorials and new search to find what they need. I don’t know even if there is a universal answer to this, because people’s needs are different. But I don’t know. I don’t have an answer for you. Sorry. Am I free to go? Yay!
