Additional Meeting: Content Development with NodeSchool workshoppers as a base for content

[bnb]

Per discussion in today's meeting (#24) we'd like to proceed with an additional meeting to begin defining how we pull this content together.

This stems from discussion around #18 and the realization that NodeSchool workshoppers aren't actually a part of the NodeSchool org, but rather the workshoppers org on GitHub. The majority of the Node.js content is written in Markdown and available under an MIT license, which means that we can probably use it as a baseline (with full credit to NodeSchool and the Workshoppers org) unless there are any unforeseen barriers.

We also discussed reaching out to the learn-you-node contributors to be part of this discussion, so I'd like to invite them as well - I'll create an issue in their repo and point back to this issue.

Also, based on some of the discussion in the meeting: We'd like to invite @jennschiffer to discuss Glitch and how we'd be able to effectively work with Glitch as a platform. We've seemingly narrowed our decision for a to RunKit and Glitch, but understanding the interplay between content and editor is super important and having Jenn would be extremely helpful context for the initiative.

[tolmasky]

Hi, I work for RunKit and was pointed to this issue. We would certainly love to help power live examples on nodejs.org! Our embed docs are here and I thought it would also be useful to list a few points we think are a particularly good fit for nodejs.org:

1. We support every major version of node -- so for example switching the docs to node 0.10 will mean the examples will run in node 0.10. RunKit is committed to continuing to support every version of node forever. This is great in our opinion for comparing behavior between versions, which is a common documentation task:

2. RunKit aims to support every version of all the 700,000 packages on npm, and they're all already "pre-installed", so no waiting on install time or missing long-tail packages. Just type require("canvas") and it's there, or require("[email protected]") for other versions.

3. We've spent a ton of time making the debugging experience great on RunKit - we for example show rich stack traces that let you navigate the code inline and read nodejs docs inline as well (very meta ;) ). You can read more about this here but can see it in action right here:

4. We have an "endpoint mode" that allows users to spin up custom web services, you can see this on expressjs.com's Hello World example: http://expressjs.com/en/starter/hello-world.html

Finally, one thing that's different about the way RunKit works compared to other similar tools is that with RunKit the code would live on nodejs.org. RunKit embeds works a lot like highlight.js -- it takes the existing static code already on your site and replaces it at runtime with a widget that allows you to run the code. With other services, you often have to create and host the examples on their respective websites, which you then embed through an iframe. We're think its critical for code to not be stored on third party services because:

1. With RunKit the code samples get edited in your markdown and thus go through the same contribution and review process as everything else. You aren't editing documents on another site and then pasting URLs that end in a new hash into your docs. Bugs in examples get fixed through normal pull requests and exist in your project's history.
2. It's very easy to automatically generate the embeds from local code sources as there's never any need to use an API to generate an external document.
3. If our site is unexpectedly slow to load or ever goes down, the code samples simply render in their static form vs. leaving a blank box.

Anyways, our primary goal is to enable these exact experiences. We really want a world where every code example online is immediately runnable and usable. We're happy to help in whatever way we can (even if you don't end up using RunKit!).

[jennschiffer]

Would be happy to join the next meeting to provide that context! We've had a big week this week at Glitch, launching our Node debugger interface with Chrome dev tools and our git Rewind interface - all to enhance the Node dev experience, not to just abstract development workflows that lock folks into the editor, which I think is inline with the mission of showing ready-working examples on the Nodejs site. If you need an email for the meeting invite, [email protected] is it!

[amiller-gh]

Hey all! I set up a Doodle to schedule our breakout meeting for the "Getting Started" and "Advanced Tutorials" sections of our "Learn" pages.

Because we'll be getting deep in the weeds with this one, I'm going to try and find a 2 hour block for us to meet and workshop content structure ideas. I'll try to find a time that the majority of us can meet for at least one of the two hours 👍

My thoughts on deliverables we want from this meeting:

• Determine our target audiences for both sections and determine high-level expected outcomes.
• Outline top-level "learning paths" (based on content from NodeSchool and other sources)
• For each section defined, begin to come up with:
  • Topic Description,
  • Key Takeaways and,
  • Example / Exercise Description (if applicable)

Let me know if you think these goals are off the mark, or missing anything!

@nodejs/website-redesign, if planning this type of content sounds like fun to you, please attend!

@tolmasky and @jennschiffer, we'll mostly be very content-focused in this meeting, not implementation focused, but if you want to attend and get an idea of our potential use-cases – or even help us deep dive in this discussion – please feel free to call in!

Everyone, feel free to mark your availability here:
https://doodle.com/poll/hx7zwckei2k7ueyt#calendar

[amiller-gh]

Closing because this meeting has happened and we're well beyond this discussion in other issues 🙏
Related: #9, #60 and #21723.