Full Stack Documentation

Welcome back. It's another week, we've moved on a little bit.

All right. So while I was researching for this talk, I stumbled upon a 19th century sea shanty about the evolving techniques we use to deliver HTML to our users. It was very ahead of its time. I thought I would share it with you. It's called the Web-O-Man, and some of you might know the tune. If you do, I'd love for you to join in. If we can get some people singing along in here, it will make this whole thing so much less awkward for all of us. At the very least, please help me keep time.

Come on. The once was a place to run your code in US-East-1. Non-containerized node requests came in. Replies were bestowed from the Lambda far away. Soon, nay, the server responds to bring us mock-ups to look upon. One day when the Javascript runs, we'll take our page and go. The cold starts held the data back. Lidane said you should use Jamstack. It sounded good, so he gave it a crack for a while anyway. Soon, nay, the server responds to bring us mock-ups 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, nay, the server responds to bring us mock-ups 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, nay, the server responds to bring us mock-ups to look upon. One day when the Javascript runs, we'll take our page and go.

Once more.

Soon, nay, the server responds to bring us mock-ups to look upon. One day when the Javascript runs, we'll take our page and go. Last time. Soon, nay, the server responds to bring us mock-ups 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 is 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 we were singing describes an important trend in web development. A lot of computation is moving away from servers and single origin functions and out to the network edge. Thanks to things like Deno and Fastly, Cloudflare, the Vercel functions which run on Cloudflare and Netify, 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 SolidStart. And 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 this is 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 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 in a Lambda, it runs in the Edge, it runs in your browser. Soon it'll run in a service worker. And you can deploy it to any platform you like. There's no lock-in. When you create a 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 VEET, so it has this world class developer experience. If you haven't used VEET, I encourage you to give it a try. It has file system based netted routing. It has a tiny footprint. Both on the client, we all know 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.

As flexible output, you can do dynamic server side rendering. You can do static site generation. You can build a single page app. You can mix and match all of those things within the same application. It's built on top of Svelte, which I'm biased to, but I think that means that 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. These are 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-tos that teach an experienced user how to do specific things with your tool. Then 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-tos, these are both for your existing users, while how-tos and tutorials are all about step-by-step guides for achieving some goal. And, in fact, we can plot these as a quadrant, as 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 Daniela Prosida, and 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, deartaxis.framework.

There's an often-mangled quote that I really like, that, 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-tos 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. A 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, okay. This is 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, and we have a CodeMaker editor, and people honestly freaking love this tutorial.

So many people have told us that this is the reason that they became Svelte developers, even people on the core team have said that. And other frameworks have followed suit. So this is view'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 SvelteKit's tutorial. It's currently a 404 because the existing tutorial that we built only covers Svelte itself. It does not cover SvelteKit, the full stack framework. And we don't think that's very good. We want to be able to teach people how to use SvelteKit the same way that we currently teach them how to use Svelte. And 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, you know, 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.

But we found 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. And 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. For 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.

In 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, strops 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. The 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 Kimble, 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 he does in fact have his work cut out for him. Principle here is that students are chaos demons.

Finally, sister Mary Clarence from Sister Act 2, who is brought in to save the 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 Delores 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 WiFi is going to be kind to us today. Let's try that once more.

All right. Here we go. 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 Svelte. 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. We want you to be able to reload the page and get back to what you were doing without worrying about losing your progress. 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.svelte, 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 abeying 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. 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. She's 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 arny face as she completely broke everything in ways that I could never possibly have imagined. 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 the creative ways in which they break it. As a result of that experience, we were able to make 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 SpeltKit as well as Svelt. We have some work in progress documentation about SveltKit here. Let's go over to this. You'll see that now in the file tree editor we don't just have a single component, we have an entire project with a package.json and SveltConfig and all this other stuff. The purpose of this section is to teach you about roots. We have two roots, an index root and an about root. If we're on the index root, then we can click the about link and it will take us to the about page.

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. Svelte depends on node because it reads from the file system and yet we're running it in the browser. We're cheating a little bit. It says local host. That's because I'm running this on my own machine. If we look over here, inside the learn.svelte.dev we've created a bunch of different apps and they look like this. If I look at the index page. We've literally just written it to the file system. 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. So that brings us back to the 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, repplet, 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. And 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 will just start mining Bitcoin on them. And we don't want that. So we want to have an authentication barrier before people will 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 an editor 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 web containers and it's kind of magical. I'm probably not gonna 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's 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 and that means 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 web container 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. 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 dependences like Vite and ESBuild, we've written our application filesystem, and we've started a Vite DevServer, 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 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.

So let's go there. Yeah. All right. Well, it looks really promising. Thank you. And looking forward to playing around with 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 that. Quasar.dev. If I... Oof. 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 Svelte kits should be able to target environments like that. Once we get Svelte kit one 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. No.

On the roadmap. Yeah. 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 them? Yeah. It's actually very simple to get started with a Svelte kit 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 setup that is very similar to the one that you have in the browser. So we tried 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. It'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, you know, that is the constituency that is typically least well served by documentation. And you know, 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 of course It's very 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, but if you want to continue the conversation with Rich, he's going to be at the speakers booth or on spatial chat for the remote audience and of course Scoff, you're an online person. So thanks a lot, Rich. All right. Thank you. All right.