 Next up, we have Beyond Copy and Paste, creating interactive documentation with Maria Nagaga. Thank you so much, Mika. Thanks everyone for staying tuned with .NETConf 2019, and thank you for listening to my talk. So my name is Maria Nagaga. I am a Senior Program Manager on the Visual Studio and .NET team. I want to talk to you today about interactive documentation and how we think about that, and how it's important for our first-time developers as well as developers who are continuing to grow and build on our platform. So let's talk about documentation. Documentation is how we build trust with our developers. It's how we educate people, it's how we sell our products. Good documentation means that we are as invested in our product as much as you are. It's important as we build our documentation from first-time developers to people who are building code every single day, that we make sure that their on-ramp is as smooth and as effortless as possible. So let's talk about documentation today for a few minutes. With documentation today, it's getting really good, but there are still a few assumptions that we continue to make about our customers. First is the assumption of knowledge. Sometimes when content creators are writing documentation, they assume that the people coming to our documentation have prior knowledge of the framework and the languages being taught. The assumption of tech. As a content author myself, I sometimes continually find myself thinking of my experience as the only experience. I sometimes reference the operating system I'm using. I sometimes reference a version of Windows. I always assume that someone has as good internet bandwidth as I do. So a good example of this is providing links to certain specific downloads as well as screenshots that only reflect a particular operating system. The last one is the assumption of time. We are all really guilty of doing that. We assume that the people coming to read our content or use our videos or our documentation have more time than they do. Usually when people are learning things, trying new things or testing something out, they have a limited amount of time. Whether you're an educator, a hobbyist or a seasoned developer, you're probably doing this over your lunchtime or just before you go to bed or just before you start work. So we need to make sure we cater for that. So when we look at documentation today, majority of the documentation looks like this. It's static code. If we think about this from the perspective of a net new developer or brand new first-timer, they're often left wondering, what does this do? So we then go to Stack Overflow, we copy and paste a bunch of code from here and there. But then we still have for the challenge, especially as first-time developers, what template do I use in Visual Studio? What libraries do I need? What do all these error messages mean? We are telling people that for their first few lines of code, there's a huge on-ramp or even just to run a sample. For seasoned developers, you're probably working really fast and you don't want to copy and paste code in and out of your code base. You just want to see if this is the best thing for you. So we've noticed one thing as we begin to improve our documentation, our expectations have changed and we expect more from the people building our content to do more. Video has done great work in this space. We just launched right now with .NET videos on how we are investing in videos and how we are making sure that our developers have an interactive experience where they're able to listen, pause, and rewind. But still, we're assuming a bit of time on your side, but it's really good content, so please go and look it up. Another thing is interactive snippets online. This has actually become a requirement for languages and frameworks. When you can see the popular languages like JavaScript and Python allowing people to test APIs and syntax right within the browser, but we're also seeing it in popularly emerging languages as well such as Scholar and Go, where people are able to interact and test APIs right within the browser. But this is just a few pieces of the puzzles. So we have video on one side, we also have syntax iteration online. However, people want to have experiences that feel as native to the experience that they would have in the browser. We're seeing this in places like Microsoft Learn, where people are able to try and test things out, which would be similar to what their local experience would be. So when they do transition into an offline experience, it feels vaguely familiar. But then we also have the concept of trying. Now, this is something I constantly do. If I want to try out a new NuGet package, I will create a throwaway package, see if it's working, I will delete it, I will do it again. But you're seeing places like MPN with the help of companies like RunKit, creating these experiences online. We should be able to try out our NuGet packages and see what they're like right within the comfort of our browser. I'm hoping continuing to see here is a narrowing of the divide between documentation and code. The reason why we're seeing this is the landscape is continuously growing. We have developers such as people who are watching the show, writing blog posts every single day. We have hobbyists and the hobbyist field just keeps on growing from makers to web developers, mobile developers, IoT from social media influencers, where they're just constantly learning how to own their own online experience. We have data researchers who are using and mining data and making these analytical choices to make more informed decisions. We have educators, both CS educators as well as non-technical educators, where we're seeing in primary and secondary schools all around the world, where non-technical teachers are given the task to unwrap the next generation to be comfortable in this new world of coding. Finally, we have our students who want to explore and learn as much as possible and we need to provide those opportunities for them. When we're creating these new experiences around documentation, especially at Microsoft, there are things that we wanted to make sure that we landed very comfortably with the customers. We wanted to make sure that they had up-to-date documentation nice and fresh, referencing articles that were from 2019 versus 2003. We wanted to make it engaging and engaging is not just about making it flashy and cool. You want to make the navigation really easy. You want someone to land on a documentation page and know where they need to go. You also want the steps to be clear and quick and easy. If you go to .net right now and you go getting started, you will see how to get rough and running in 10 minutes, giving people the moment to feel empowered in 10 minutes or less. Finally, we wanted to create a friction-free learning experience. We wanted someone to be able to go onto a webpage and learn about the language without having to install all the tools or know everything. In 2017, we launched an interactive online experience with a product that I built called Try.net, which allows people to experiment and try.net the language within the browser. Let's talk about more about the Try.net interactive experience and what we offer there. We have our initial goals were in 2017 was to have an interactive documentation online, bringing us up to speed with the other languages that had been providing this for their customers. Most importantly, we wanted it to be login-free. We wanted to make sure that someone didn't have to install everything on their machine in order to just write console.writeline hello world. We wanted you to give that quick win. Finally, we wanted a fast on-ramp. We wanted it so you could edit the code online, click run, and see the results. We wanted you to feel that moment of success. But we also noticed that Try.net is growing, and those are some of the wonderful things I want to show you with you today. So when we first began in 2017, we wanted a friction-free online experience, and we did that. With Try.net and you go to docs.microsoft.com, you're able to run C-sharp code right within the browser. But as we began to notice that, there were certain difficulties. First of all, what happened if someone didn't have good internet access? What if somebody wanted to do this locally on their machine? How are we creating that experience for you? Also, we wanted to make a cheaper alternative that allowed people to run things easily within their website. And luckily, in 2018, we also got Blazor, and it allowed us to pivot from running things in containers on Azure Container instances to running things on the client side with Blazor. And not only that, because we created these experiences, it also allowed us to create a local experience with the.net Try.global tool. And if you look at my slide right now, we have a student in South Africa who calls this one of the most influential things that he's used that allows him to go and share C-sharp experiences with his fellow students. So we thank you and we hope that you continue to use us. And then we have a special surprise that I think a lot of you didn't expect, but we also have.net running in notebooks. And I'll be sharing that demo with you later today. So let's go and see some demos now. Okay. So as I said, Try.net started in the browser. So if you go to any single sample on the docs.microsoft.com quick starts, you notice that we have an editor right now. You can copy the code over, run it, and you have the direct results. You can also edit it easily right within the browser. So you're not restricted by what is in the code and you run it again. This is all running on Blazor. It's all running on the client side. It allows us to create opportunities where people could possibly add this to their websites as well, which we're hoping to enable in the future. But I also talked about the offline experience. If any of you have ever done a workshop or done a tutorial out there, you've probably had to get people to download the tools, clone the repo, make sure then the right operating system. And before you know it, it's two, three hours into the workshop and nobody has done anything. We wanted to make sure that people could be just successful with a .NET SDK and the .NET Tribal Global Tool and get things up and running. So I want to give you a quick demo of that. So we have this repo. It's our samples repo. You can go to .NET Try slash samples on GitHub and you'll see four clear instructions where we'll tell you to install the .NET Try Global Tool, which is available when you get today. Clone this repo. Then once you have this repo clone, I want you to go into the directory and type .NET Try. So as someone who prepares for demos ahead of time, I did the first three steps ahead of time. So I'm going to go right into here, type .NET Try, hit run, and what this is going to do, using Kestrel is going to start up my browser and it's going to give me an interactive markdown experience. If you look at the top, this is an MD file. So I'm going to continue into introduction to programming with C-Sharp and you'll notice that you have a list of instructions. It's like an interactive book. Let's go ahead and run this code. Sometimes the first run can take a few seconds, but bear with me. You have Hello World. I can go in, change it again, and I will put in my name, run it again, and I see the results. This gives people the flexibility to learn and experiment within the browser, giving you that nice interactive experience. So I hope that you'll give it a try for the next workshop that you're doing, or if you just want to give it a just try it out. But the big question here is how are we doing this? How are we able to have this mix of interactive code, C-Sharp code with a markdown file? So I'm just going to go over to Visual Studio Code and show you some of the magic that we're running. So I'm just going to close up the server here. So this looks like markdown that you've probably written in the past if you've done anything with a readme file. And if you add any sort of language, features within your markdown, you usually have to use a flag. So you'll notice that we have something called C-S, which is a C-Sharp. We're pointing to a specific region, right? So this is general C-Sharp regions called intro. We're pointing to a source file and we're pointing to a program.cs in my app. So let's see what this is. If I go over to my program.cs, you will notice that I have a couple of regions that are already have a bunch of switch case statements and I have a region called intro. So if I edited this and I said hello.net.com and I saved this file and let's just go ahead and run this again, .net try. I go back into my introduction to C-Sharp and I've edited it, right? So there's a seamless difference, but another thing that we have to be careful with is that if anyone's written documentation, sometimes it gets out of sync. Like how do we support our backing project as well as what we're putting in the documentation and we wanted to make sure that we supported that. So let's make some quick edits. Like how do we verify code? So I'm going to go over to VS Code again and I'm just going to make some clumsy mistakes over here. I am going to remove the semicolon, save that. I am going to change this from intros, from intro to intros. I'm going to save that again. And I want to show you a new addition we added called .net verify, right? So what it's saying, sorry, it's .net try verify, right? So this is going through and it's actually checking your markdown and checking your backing project to make sure that everything's going okay. And you'll notice that it says, hey, you're missing some things here. You're missing a semicolon and we also haven't found the intros region. So we wanted to make sure that before you hit push into GitHub, you're able to actually see any issues that might pop up, okay? And we're allowed, we enable you to do that. If you're someone who would prefer to see this in a UI format, it's also supported on the server, on the UI side as well. So I'm just going to click, do this, do .net try. It's going to launch the local host again. And if I go over to the introductions, it will tell me that the region hasn't been found. So on both sides, you have this experience where users are easily able to catch what their mistakes are. So let's go on since we've seen that. If you want to look at this more, you can go ahead to our GitHub repo and please give it a try. So I want to show you a little bit more and other experiences that we've been creating. So I showed you the .net try global tool and I showed you .net try running in the browser. But I also wanted to show you something that we just did this week and I'm really looking forward to hearing your feedback. If you go to our GitHub repo and you do .net slash try and you scroll to the bottom, which is pretty long, you can notice that we have a lot of files in there. You'll notice that we have the .net try enable back but we also have launch to binder. Now binder is a project, an open source project where it's able to point to a GitHub repo and take out all the notebook files and run them in the browser. So they spin up a nice container and you're able to look at it right within the browser. Over here, I already got this started. This is C sharp notebooks. Oh, sorry, let me start that again. That's launch binder. This is going to take a few minutes because it's configuring a container for us and the beauty of live demos is that this will happen as the circle spins around but what we wanted to show you here is that we want you to be able to try the .net notebook right within the browser. We wanted you to play around with it. Let me make this into C sharp. We're going to go into samples and I have an housing ML sample right here. So let's walk through this experience. You can install and you get packages, right? So this allows you to customize it, add any new get packages that you'd like. I'm going to hit shift, enter. What this is doing, is it going to new get? It's installing those packages for me. This will take a few minutes but as we want you to know that if you are using this on your side, you can install as many packages as you would like. You can notice that we're using the ML package or using auto ML and we're also pulling the data frames new get package as well. But as that's installing, let's look through the rest of the code so I can run through it. We're able to use our packages in the next cell as some of you might know. Notebooks have cell by cell execution. We also wanted to make sure that people had graphs being able to plot there. So we wanted to make sure that people were able to display graphs, scatter plots right within the new get packages, right within the notebook. Wanted to make sure that we made this feel authentic to people who are coming from the Python notebook space but we also wanted to make sure that our customers who are regular.NET developers that this also felt authentic and natural to them. So I'm gonna run the next browser. Maybe it's our next cell. Shift-Enter. All right. And as you can see, we have a nice table that has been delayed. We've actually been able to display table of the housing data. We can also plot some graphs which I think would be the cool thing. So let's start looking at some cool stuff. All right, let's run that again. All right, so I'm gonna go over to docs, samples, and housing. Let's pull in some packages. Bear with me, I am so sorry. But this should take a faster time than next time around. We've installed our packages. We're waiting for just one more which has been successfully installed. Let's run this, the housing data, right? So what we wanted people to be able to do was see the graphs and customize these graphs authentically. I don't know. Okay, so let's give it a moment and what we should see in a bit is a histogram that shows us a trend of all the housing data across California. While we're doing that, okay, let's give it one more time. Think the third. Yes, there we go. It just needed one more time. If you hit it hard enough, it will happen. So what we can see is that we have a histogram that shows all the data. If you're someone coming from the notebook space, we also have support, so you can zoom in and see these things in more detail. We also wanted to make sure that you're able to do more interesting graphs like scatter plots. So let's run this, give it a moment. All right, and as you can see, we have a scatter plot and guess which state this is? California. Sorry, I don't have a live audience. It's California. As we can see, the pricing is pretty high, but let's say I wanted to zoom in a little more. I can do this. I can zoom in on some of the hotspots. What this will do is I will actually cancel out everything else. So we wanted that rich interactive experience that people have come to expect and we're looking forward to your feedback. So if you have any questions on how to get started with the .NET kernel, that would come at a rounding nighttime. We won't have anything for people to try at the moment. However, we do have the MindBinder experiences available right now. So if you go over to our GitHub page and you'll be able to launch it right there from launching my Brander. So we have a couple of minutes for questions, I believe, when we have a chance and we can give it a go. Are we ready for questions? We are ready for questions. Fantastic. Well, hopefully you can see us here. I brought my brand new phone. Hello. That was really awkward. Well, you know, the first thing that's kind of cool is this one right here, Mika. How do you feel about what she just showed us? I think it's awesome. Have you ever tried, have you ever tried try.net? You're going to love this. I'm reading upside down. I'm going to read it. Looks like a fairly simple way to learn and write some C-sharp code inside your browser without having to first create a visual SEO solution. Plus, lots of sample code aims at new learners. Check it out. You have a fan. Yay, you really do. And there's a GIF, and I'm going to say GIF for all of you out there listening. I will not say GIF, it's not peanut butter. Okay. The Australian guy going like this, two thumbs up. All right, what else do we have over here? Let's see. Wish this had been around when I was working on Biff Frost. By Frost? By Frost. A few years back, looks really impressive for .net open source projects. Like I'm wondering if this guy's Thor. I think he might be. Okay. I think he might be. Chris Hemworth, hi. Yeah. Oh yeah. Of course. Hey, Chris. Hi for me too. Yeah, we'll say hi. All right, here's another one from John. Great to see the improvements Microsoft has made in language platform documentation. I still remember the huge stacko books from C6.0. That's a long time ago. Should have included a back brace with the product. This is pretty cool. I love the idea of being able to learn and read as you go. I'm personally a fan of notebooks. I'm so glad C-Sharp is coming to it. And the try.net stuff is really cool. So if you could give people one takeaway from your session, what would it be? It would be number one. Can it only be one or can I give two? Can you give as many as you want? Okay. This is your session. So number one, please go and try the .net try global tone. Give it a try. Make sure you're using it for your next workshop. We are looking forward to hearing how you're doing with it. We've had people try it with workshops that are pulling from Azure Functions. So I would love to see more workshops with that. Also, if you want to give the binder experience a try, let me walk through that experience one more time. One more time. So people can look at it because I had some technical issues because that's the world. So let's do that. So if you go to our GitHub repo which is .net slash try, you scroll down all our code base, you'll notice launch my binder, right? So when you launch my binder, what this is doing is that it is spinning up a container for you and you're able to actually start running and writing that code right within the browser. So it's pulling in the .net core SDK and all that kind of stuff. Now for it to even look nicer, look at it in the lab format, which I just think is always like a nicer way to look at this experience. I'm a fan. It's really cool. I just want to point out, we do have F-sharp support. I don't know if people saw that. Is that because Philip's next? Philip is next and I almost didn't tell, I didn't say it, I didn't say it. That's right. We do have F-sharp support. So if you went there, you go to docs, there's an output. There is a bug which I can fix right now. Hit run, but this has all the nice F-sharp expectations that people will have and my team will continue to work on that. Fantastic. If you look at C-sharp as well, let's go up one. Look at C-sharp, you will find two different samples. You'll have one which is the housing sample and just to give reference to this housing sample is literally pulled out of a data science book and Eric did a side by side and was able to replicate this entire experience right within the browser. And we also have a repo one, which I should have run to show you how we are actively keeping track on the issues that you're doing and we are actively trying to close them. Fantastic. Yeah, and then wait for ignite so you can start installing the bits on your machine. All right. Nice. We have another question. Is it possible to integrate try.net with doc FX documentation? Try.net and doc FX. Not at the moment now. Okay. Okay. And I think there's one more. Is it this one? Yeah. Can I take a subset of the try.net code and use it to incorporate C-sharp scripts within existing applications? Ooh, Jeremy, good question. Yes, you can. Just look at our repo and ask us questions. And here's another one with another gif. Also, it's gif, Yoda. Why is one? It says, so do what you can as there is no try. Try.net.net. Like, I love it.net.net. The cool with Jupyter notebooks. Look at that. It's like, what was the thing again? I'm trying to like parse it. This is really good stuff. Okay. So do what you can as there is no try. Try.net. The cool with Jupyter notebooks.com. I will decide for that. I think try.net is cool and we're also excited about the Jupyter notebooks experience. Oh my goodness, she is so good. Are we ready to go to the next session? Yeah, we have what's new in F-sharp with Philip. So, Philip. Now is it Philip or Phil or is it like, do I have to say it with a British accent? Philip. Oh, no.