Channel
Interviewed Person
Conferences
Building a better, faster Web starts with creating interactive documentation. Here’s how to get it done with Sylwia Vargas, Developer Advocate at StackBlitz. Make contributing to docs seamless: https://vercel.com/home
Vercel
Interviewed: Conferences
- Writing documentation means updating markdown files. I find it really frustrating to fix a typo through an IDE because IDE was optimized to work with code and not with content, but is there a better way? My name is Sylvia Vargas and I'm a Developer Advocate at Stagbees.
I want to talk to you about building documentation with Next.js. Many of you are familiar with Nextra as static side generator used for docs and blogs based on Next.js. Say you wanted your users to instantly try your program out. You could embed an interactive example onto the page. Our community has created some stunning work with our Embeds. Just look at these gorgeous examples of pages and courses.
So let's do it together. But I am not a contributor or maintainer of Nextra so I need to fork and clone the repository, install the dependencies, resolve possible conflicts and run the Dev Server. Or do I? I have a surprise for you to edit this page. Let's find, edit this page on GitHub link. Okay, I will click on it and no, this is a markdown file.
It's not helping me. I don't know how these changes are gonna look. Okay, let's click on the preview and, nope. Frustrating, It doesn't look anything like my page and it cannot look like my page because there is no Dev Server running. to see how this changes are going to be rendered on my page. I need to clone the repository, render dependencies and run the Dev Server. This is a lot of work for one small change.
Okay, let's try something else. Let's go back to our homepage and let's try adding PR that new to this link. What will happen? Will it work? I don't know. Let's see. Can I click it? Let's see what happens. Web publish everyone. It is a tool designed to make content creation
and content updates friendly. On the left, you see an editor underwrite. There is the Dev Server already running. As I type it updates I can instantly see how my changes will look on the page. And the best part, well, it can work with any framework and it is free for open source projects. So let's add the interactive example, shall we? Okay, adding an I Frame,
pasting the URL and done. Looking good? Yes, it is. Our Embed is ready so let's submit a PR. As I click on this button the publisher will do all the heavy lifting for me. It'll fork the rapport, commit my work, push the changes and prepare a PR and that's it, ready, done. With publisher is not only for blogs or docs
you can edit any page your lending page or your marketing page. You can invite your non-technical colleagues to join in the fun. Think about your marketing colleague or your friendly designer friend or even my mom can now edit our landing page. There is more. Now that our PR is ready we can use another tool called Code Flow IDE to review it.