Diagnostics WG and Webiste Redesign WG collaboration on diagnostics guides

Open mmarchini opened this issue 4 years ago • 4 comments

(not sure if this is the right template and label to discuss

Documentation Is

[ ] Missing/Needed
[ ] Incorrect
[ ] Confusing
[x] Not Sure?

Please Explain in Detail

The Node.js Diagnostics WG have been doing deep dives on several aspects of debugability and observability features on Node.js for the past year. We gathered content and knowledge which is intended to be published on the website at some point. I was just looking at the new design, and I believe the content would fit better here than on the old webiste :)

I see there's already some content related to diagnostics, like How to log an object in Node.js. There's also a differences between development and production, which is aligned with discussions we had about a page (or set of pages) outlining best practices to publish application to production to ensure the application has appropriate observability settings.

Right now most of the content we generated is spread across uncurated Google Docs files, and we've been slowly curating this content and moving it to a folder the Diagnostics repository. Instead of focusing on the tools, we're trying to focus on use cases and for each use case we outline which tools and techniques can be used. This is also reflected on the navigation, which allow users to jump to the appropriate pages based on which symptoms their applications are experiencing.

Would the Learn page on the new website be the appropriate place to publish this content? I see the content is already using markdown with some extra metadata, so it should be straightforward to move content we already have to here (I'm willing to do the work). I don't think those guides fall under Getting Started though, could we add a new category Troubleshooting or Debugging or Diagnostics or ...?

I'm also available to join the next website redesign meeting if y'all want to discuss it further there (I'm also happy to discuss it async here, whichever works best for you) :)

Jun 18 '20 23:06 mmarchini

I think think adding more content on how to debug a Node app in production is a great idea and would fit in the learn section of the site. I also like the idea of having a new category for it. I'm 👍 on Diagnostics or Debugging.