Transcription
All right. So while I was researching for this talk, I stumbled upon a 19th century sea shanty about the evolving techniques that we use to deliver HTML to our users. It was very ahead of its time. And I thought I would share it with you. It's called the Weberman, and some of you might know the tune. If you do, then I would love for you to join in. If we can get some people singing along in here, it'll make this whole thing so much less awkward for all of us. At the very least, please help me keep time. Come on. So once was a place to run your code in US East 1. On containerized node, requests came in. Replies were bestowed from the lambda far away. Soon, hey, the server respond to bring us markups to look upon. One day when the JavaScript runs, we'll take our page and go. The call starts, hold the data back. Lidane said you should use Jamstack. It sounded good, so we gave it a crack for a while anyway. Soon, hey, the server respond to bring us markups to look upon. One day when the JavaScript runs, we'll take our page and go. Static files are great unless you need something from a database. Then you'll need to make a request to chase the spinners away. Soon, hey, the server respond to bring us markups to look upon. One day when the JavaScript runs, we'll take our page and go. If you don't want to fetch your data late, just render your page inside V8. Life on the edge is pretty great. Friends, this is the way. Soon, hey, the server respond to bring us markups to look upon. One day when the JavaScript runs, we'll take our page and go. Once more. Soon, hey, the server respond to bring us markups to look upon. One day when the JavaScript runs, we'll take our page and go. Last time. Soon, hey, the server respond to bring us markups to look upon. One day when the JavaScript runs, we'll take our page and go. We did it. You magnificent people, I love you for joining in. That could have gone horribly, horribly wrong. Hi, let me introduce myself. My name's Rich. I work on a user interface framework called Svelte. I'm one of hundreds of contributors. And I work on open source full time at Vercel. The song that we were singing just describes a really important trend in web development. A lot of computation is moving away from servers and single origin serverless functions and out to the network edge. Thanks to things like Deno, Fastly Edge, Cloudflare workers, Vercel Edge functions which run on Cloudflare workers and Netify Edge functions which run on Deno, someone like me who knows very little about back end stuff is able to deploy an application that is instantly available within milliseconds to users anywhere on the planet. I think this is a tectonic shift in how we build stuff on the web, even though there are some unsolved problems about where we put our data, for example. Meanwhile, front end frameworks are also being affected by this trend. When you think about frameworks, you probably think about React or Vue or if you're a little bit more of a JavaScript hipster, you might think about Svelte or Solid. But increasingly we don't use these frameworks by themselves. We use meta frameworks like Next, Nuxt, SvelteKit and Solid Start. These are toolkits for building an entire application as opposed to just a few components. They bring a build tool, a dev server, your routing, all of that stuff. And crucially, as well as running in the browser, they run in a server environment as well. We can call them full stack frameworks at the risk of upsetting the angry nerds who police the use of that kind of terminology. And so there's an interesting convergence happening. Front end technologies are starting to claim back end territory while back end is becoming more accessible to those of us who are traditionally front end operators. In many cases, edge functions use the same web APIs that we're used to using in the browser. So I work on SvelteKit, which is the official meta framework, the official full stack framework for Svelte, and we're pretty proud of what we've built. We think it's very compelling. It runs anywhere JavaScript runs. It runs on Node. It runs on Lambda. It runs on the Edge. It runs in your browser. Soon it will run in a service worker. And you can deploy it to any platform you like. There's no lock in. When you create the project, we don't ask you where you're going to deploy. You can figure that out later and change your mind. It's built on top of web standard APIs like request and response. It uses Vite, so it has this world class developer experience. If you haven't used Vite, I really encourage you to give it a try. It has file system based nested routing. It has a tiny footprint, both on the client, we all know that we should minimize the amount of JavaScript that we serve to the client, but also on the server. When you're using serverless environments and Edge functions, it's important to minimize the amount of JavaScript that needs to boot up in order for that function to start serving responses. It has flexible output. You can do dynamic server side rendering, static site generation, build a single page app, and mix and match all those things in the same application. It's built on top of Svelte, which I'm biased to, but I think that means you'll be able to build an application more quickly using SvelteKit than with any other framework or your money back. And, of course, the framework itself is fast. As my boss likes to say, the combination of Svelte and Vercel Edge functions lets you do dynamic at the speed of static. But there is one big question mark looming over the landscape of full stack frameworks. And the question is this. How on earth do we do full stack documentation? No one has really solved this, I don't think, until now. But before we get into that, we need to talk about what we talk about when we talk about documentation. So, documentation is one word, but it's many different concepts. I like to think of it as a cake, specifically a Battenberg cake. I don't know if you have Battenberg cakes in mainland Europe, but you should. They're terrific. This Battenberg cake has reference documentation, which is what we tend to think of when we think about documentation. This is your interfaces, your APIs, and so on. We have explanatory material that give you a higher level overview of some of the concepts in your tool. We have how-to's that teach an experienced user how to use, how to do specific things with your tool. And we have tutorials, which teach people how to use the thing in the first place. And the reason that these are so often conflated by open source projects is that they all overlap in interesting ways. Tutorials and explanations are both concerned with learning, explanations and reference material are both about buttressing your theoretical knowledge. Reference and how-to's, these are both for your existing users, while how-to's and tutorials are all about step-by-step guides for achieving some goal. In fact, we can plot these as a quadrant, a series of quadrants, with learning and application on opposite ends of one axis, and theoretical knowledge and practical steps on opposite ends of the other axis. I didn't come up with this. It's by a chap named Daniella Prasida. If you're involved in documentation efforts, and you should be, because I believe that documentation is at least 50 per cent of working on any software project, then I encourage you to check out his talk, What No One Tells You About Documentation, and the accompanying website, deataxis.framework. There's an often mangled quote that I really like. Tell me and I'll forget. Show me and I may remember. But involve me and I'll understand. Your reference docs are good at telling you what to do. Your explanatory material and your how-to's are good at showing you how to achieve some specific task. But if you want people to actually learn the thing that you're offering them, you need to involve them, and that is where interactive tutorials come in. Tutorials are the hardest form of documentation to write, and they're the most frequently overlooked but I believe they are the most important. Obviously, you need to have reference documentation, but you can have the best reference docs in the world. It won't matter if no-one is using your thing. Reference docs are how you serve your existing users, but tutorials are how you create new users. I was first awakened to the power of interactive tutorials a decade ago when I started learning Knockout, one of the OG front-end frameworks. Show of hands if you remember Knockout? All right, all the geriatrics just outed themselves! Knockout was a real milestone in web development. It's been kind of overshadowed in recent years by more modern frameworks, but in its time, it was a huge deal, and I and many other people learned Knockout through this incredible tutorial. Steve Sanderson, if by some miracle you're watching this talk, thank you for everything that you've done for my career and so many other people's. It was truly a milestone. So when we created Svelte a few years ago, we knew that we wanted to bring this idea back to the modern age. Wi-Fi is working. Great. So we created Svelte's tutorial. And it's a little bit of a Rube Goldberg machine. What we have here is Rollup running inside a web worker, and if I complete one of the examples here, you'll see that it's actually rebuilding the application on every keystroke, so we get this nice instant feedback. And it's a really easy way to learn how to use the framework. You haven't had to download anything, you haven't had to install anything, it's just right there and ready to go. We can install NPM packages from unpackage.com, we have a code mirror-powered editor, and people honestly freaking love this tutorial. So many people have told us that this was the reason that they became Svelte developers. Even people on the core team have said that. And other frameworks have followed suit. This is Vue's tutorial. Here's one from Solid, and here's one from Lit. They're all strikingly similar in form and structure because this is a format that has been proven to work. But this is Svelte Kit's tutorial. It's currently a 4.04 because the existing tutorial that we built only covers Svelte itself. It does not cover Svelte Kit, the full stack framework. And we don't think that's very good. We want to be able to teach people how to use Svelte Kit the same way that we currently teach them how to use Svelte, so we concluded that it was time to start again and rebuild the entire thing. And if we're going to do this, we want to maximize its effectiveness as an educational tool. And so we started looking at the science of teaching to see, you know, perhaps are there some pertinent pedagogical principles that could promote people's progress. And then we decided that would be a lot of work and we should just watch some movies instead because it turns out that cinema is full of examples of inspirational teachers. Teachers like Morpheus. In this clip in The Matrix, Neo is walking down the street. Morpheus is teaching him how to survive in the Matrix when Neo is distracted by the woman in the red dress. The woman in the red dress, of course, is not some innocent bypasser. She turns out to be a mortal threat. In that moment, Neo learns how he can survive in the Matrix. But he's not actually in the Matrix because Morpheus, like a good teacher, is adhering to this principle, safety first. If you want people to learn, you have to provide them with a safe learning environment so that they can learn the skills that they're going to use in real life. Another great example is Mr. Miyagi from The Karate Kid, who teaches Daniel how to do karate by making him wash cars. Wax on, wax off. Wax on, wax off. The reasons that are unclear both to Daniel and to us, the audience, until later in the film when Daniel suddenly realizes that he's been developing the muscle memory he needs to be a karate expert. Mr. Miyagi is not afraid of repetition. He is embracing repetition. Because repetition is how you learn. Repetition is how you learn. Repetition is how you learn. And the Empire Strikes Back, right after Yoda's inspiring, do or do not, there is no try speech, Luke having failed to recover his crashed X-Wing from the swamp, drops off and salts in the forest like a whiny teenager. And Yoda realizes that if he's to teach Luke about the power of the Force, he is going to have to demonstrate it himself. And so that's what he does. He shuts his eyes and he stretches out his arm and he lifts the spaceship out of the swamp to Luke's astonishment. Sometimes when people are learning, they get stuck on stuff. And it's fine. Our job as teachers is to make sure that that isn't the end of their learning journey. And so Yoda, like any good teacher, recognizes that bail them out sometimes you must. In Kindergarten Cop, Arnold plays John Kimball, a LAPD detective who, for reasons that make no sense whatsoever, has gone undercover at a kindergarten. And he believes that having spent a career working with hardened criminals, that a classroom full of young children is going to be no problem at all. And as anyone who has met young children will know, he is severely mistaken. The kids run rampant, they cause absolute chaos. And Arnold realizes that he does in fact have his work cut out for him. The principle here is that students are chaos demons. Finally, Sister Mary Clarence from Sister Act 2, who is brought in to save this failing St. Francis Academy from closure. She's teaching a music class and she's not getting through to her kids. They don't want to learn. Until one day, one of them starts to sing and the class joins in. And she realizes that she does have a way to connect with them after all. And Sister Mary, who is secretly Dolores Van Cartier, the Las Vegas performer, figures out a way to get these children to learn what they need to and the school is saved. The principle here is that you cannot force people to teach. You have to meet them where they are. So without further ado, I would like to share a little bit of what we've been working on with our new documentation and how we've been applying some of these principles. I'm going to move over to a different example here. Oops. If I can type, it would help. I'm going to see if the Wi-Fi is going to be kind to us today. Let's try that once more. All right. Here we go. So your job in each of these tutorial sections is to follow the instructions on the left-hand side to complete some exercise and learn some new concepts about how to use Spelt. And these are all short, self-contained sections deliberately, because when you're working on something like this, it's easy to make a mistake. You could introduce a syntax error that completely breaks everything. And we want you to be able to reload the page and get back to what you were doing without worrying about losing your progress. So we're deliberately not introducing complex topics over a series of tasks. Everything is self-contained. Also, this file editor here, the file tree editor, we have a single component, app.spelt, and we don't give you the ability to create new components or delete components because that doesn't serve the learning objectives. We give you a controlled environment in which it is safe to make mistakes because we're obeying the Morpheus principle, safety first. Now as a lazy programmer, my first instinct when I see something like this is to try and copy this code from the left-hand side into the code editor on the right. But as soon as I do that, this pops up and tells me that copy and paste is currently disabled. This might seem like a bit of a hostile move, but it is because this is how we learn. Repetition is how you learn. Repetition is... I'm not going to do it again. And so even though you can copy and paste, you can select the option to let you copy and paste if you need to, if you're in a hurry for some reason, we try and get you to develop the muscle memory that you're going to use when you're using Svelte outside the confines of this tutorial. Just like Yoda, we know that occasionally students will get frustrated and that shouldn't be the end of their learning journey. In this example, the idea is to get this orange dot to follow the mouse around with a little bit more personality than it's currently doing. And maybe somewhere on the journey, I make a mistake and I just can't figure out how to solve it, which is why there's a big, prominent orange solve button. I press that, and the tutorial is completed. I can play with the settings and have a whale of a time. This next principle isn't so much something that has informed the design of this platform, it's just a general principle in software development. My fiancée is not a programmer. She's actually somewhere in this room, but I'm not going to point her out because I don't want to be murdered in my sleep. But she got curious about what I was doing, and I sat her down in front of this app and asked her to complete a section. And I watched in absolute horror, pulled the Arnie face as she completely broke everything in ways that I could never possibly have imagined. And that's just what happens when you subject your software to actual users. There's a saying in the military, no plan survives contact with the enemy. I think in our field, it should be no software survives contact with users, because it won't. User testing is the most valuable thing you can do. Minute for minute, you will learn so much more if you can sit people down in front of your software and watch all of the creative ways in which they break it. As a result of that experience, we were able to make some improvements to the framework itself, and it's now much more resilient to a certain class of bug. Finally, meet them where they are. So I mentioned that the purpose of rebuilding this was so that we could also support SvelteKit as well as Svelte. And we have some work in progress documentation about SvelteKit here. Let's go over to this. And you'll see that now in the file tree editor, we don't just have a single component anymore, we have an entire project with a package.json and a SvelteConfig and all of this other stuff. And the purpose of this section is to teach you about routes. We have two routes, an index route and an about route. And if we're on the index route, then we can click the about link, and it will take us to the about page. And it's inviting us to edit that to add a link. Like so. We can click that. Turns out you can go home again. But how are we doing this? This is a command line interface that runs inside Node. SvelteKit depends on Node because it reads from the file system, and yet we're running it in the browser. We're actually cheating a little bit. You'll see that it says local host. That's because I'm actually just running this on my own machine. And if we look over here, inside the learn.svelte.dev repo, we've created a bunch of different apps, and they look like this. If I look at the index page, like we've literally just written it to the file system, and if I make some changes here, then they just get reflected on the file system, and that's how it's able to work. But this doesn't scale. We can't ask people to clone our repository and start the server themselves on their own local machine. Clearly, we need to do something better to meet our learners where they are. And so that brings us back to this question. How do we do full stack documentation? Well, there's a bunch of services out there that allow us to work with an online IDE in the browser and then run the code on a server in the cloud. Things like code sandbox, Gitpod, GitHub code spaces. And these are all phenomenally powerful tools that a lot of people use day to day, and they're very sophisticated and very impressive. I love them. I really do love them. I've used these for teaching in the past, and I think they're extremely valuable. But we don't think it's the right choice for a tutorial like this, for a few reasons. Firstly, running servers is kind of expensive, which means you need to have an authentication barrier before people can start using it. Otherwise, everyone would just start mining Bitcoin on them. And we don't want that. We don't want to have an authentication barrier before people start learning. Also, we don't want the latency that's involved in starting a server. We want to have instant hot module reloading and all that other stuff. And philosophically, we just want to minimize our dependence on third parties that could suffer outages or change their terms of services. All of those reasons are why I'm very excited about StackBlitz. StackBlitz is another one of these services that lets you edit code in the browser and then run it on a server. But the difference is that the server is actually running inside your browser. The technology is called WebContainers, and it's kind of magical. I'm probably not going to do it justice, but it works something like this. They compiled Node to WebAssembly, packaged it along with a custom NPM client, and then run it inside the browser security sandbox. So I don't need to install anything on my local machine. I don't need to worry about ransomware or anything like that. It's all just running inside the browser. A few months ago, they added support for SvelteKit, which was tricky because it uses native JavaScript modules. And that means that you can now go to SvelteKit.new and instantly create an entire SvelteKit application without having to install anything at all. And this has been an absolute game changer for getting things like bug reports and also for producing examples. So it's very tempting to just embed that whole thing inside our tutorial page and be done with it. But it's not ideal. This user interface is optimized for exploration and development. It's not optimized for learning. So we want to have more control over the user interface. Wouldn't it be great if we could take the underlying WebContainer technology and use it headlessly inside our own page? Well, that's exactly what we did. We've been working with the StackBlitz team over the last few weeks to make this a reality. So today, we're announcing learn.svelte.dev. It is a work in progress, but it works and you can play around with it. And it's trying to load over the slow conference Wi-Fi. Just bear with it. It's normally a little bit quicker than this. What's happening is we've gone to the Vercel Edge network, downloaded the app, and then that has gone and downloaded Node, installed Node on the machine. We've installed SvelteKit and its dependencies like Vite and ESBuild. We've written our application to the file system and we've started a Vite dev server. And this normally happens in the space of a few seconds, but in conference conditions, it might take a little bit longer. So let's assume that that's not going to work and I'll quickly wrap up. I think it's a phenomenally exciting time to be a web developer. We have so much power at our fingertips now. Since we started building this, I know of at least two other frameworks who have started working on something very similar. So I would expect this to become the norm of how we learn full stack tools very soon. And it doesn't just apply to frameworks. It applies to anything that runs in Node. Command line interfaces like build tools and testing tools and so on. So I want to thank the StackBlitz people for being such phenomenal partners as we've built this. And I also want to thank everyone who was involved in the development of learn.svelte.dev on things like accessibility, UX, design, testing, and so on. And I want to thank you lot. Thank you. All right. Well it looks really promising. And looking forward to playing around with it myself. And I think it's great to see how low the barrier is to try it out. And I think it's going to give you a lot of new users. I hope so. Well, at least me. So let's get into the audience questions. And I also have some Wi-Fi problems. First question from Sherman. Is there something comparable as quasar.dev in the Svelte sphere? I don't know if you're familiar with quasar.dev. I think quasar is a toolkit for building applications that can run on Electron as well as on the web and perhaps creating mobile apps as well. We don't have something like that yet. But it is very much the intention that SvelteKit should be able to target environments like that. So I would say once we get SvelteKit 1 out the door, that's the kind of thing that we're going to be looking to do. Yeah. All right. So it's not there yet. Not there yet. But it's on the roadmap. Yeah. And the roadmap is very empty. Next question is from Elliot. How do you help users move from the tutorial environment to the local environment, which requires knowledge of tools you're purposefully extracting away from for them? Yeah. So it's actually very simple to get started with a SvelteKit app on your local machine. All you need to do is type npm init svelte and just follow the prompt. And that will give you, in the space of 10 or 15 seconds, it will give you a SvelteKit setup that is very similar to the one that you have in the browser. So we try to minimize it as far as we possibly can. We're always interested in new ways to make it more accessible. But so far, we think that's reasonable. Makes sense. Next question is from Wilhelm. What difference is there in internal versus external documentation? Your examples seem optimized for new users as opposed to contributors. Yeah, that is very true. We are optimizing for new users first because that is the constituency that is typically least well served by documentation. And there's a wealth of examples and tutorials that have been produced by the community that do teach you things like how to integrate with x and y and so on. And so given that that ground is already quite well covered, we are primarily concerned with the new users. But we definitely want to use the same format to do how-to guides for integrating with those tools in the future. So again, not there yet, but it is on our roadmap. Yeah, so if I understand correctly, you've been building the platform, basically this new way of documenting for new users. But now the base is there, and it's easy to extend it for existing Svelte. Exactly. It's very easy to add new content to the platform. Yeah. All right. Well, that's all the time we have for Q&A. If you want to continue the conversation with Rich, he's going to be at the speaker's booth or on spatial chat for the remote audience. And of course, Scott, you're an online person. So thanks a lot, Rich. All right. Thank you. All right. A big applause for Rich. Thanks, everyone.
