Common MDX error documentation updates

[francinelucca]

Summary

• What route inside platform should the common mdx errors page live? Ex: next.carbondesignsystem.com/common-mdx-errors
• What should this page format look like?
  Sample content: https://github.com/carbon-design-system/carbon-platform/blob/e9372e24aa1b0504a0f11bf68e9a37ef7cf6de7d/services/web-app/pages/common-mdx-errors.mdx

Job stories

What value will this deliver?

1. When my authored content on platform has an error, I want to get more information on the error, so I can fix it.

Acceptance criteria

What requirements must be met to complete this request?

• determine desired url for page content to live in
  • we want this to live in storybook next to the mdx components themselves so it is "in context"
• design pattern for a problem/solution (i.e. how should the header/title look? should it start with text or an image? what is the general sentence structure of a solution?) (Common MDX errors problem/solution design pattern #1176)

TODO

• Incorporate design updates from Common MDX errors problem/solution design pattern #1176 into existing content
• Move page to (eventually) deployed storybook
  • Q: is this the mdx-components storybook? or the general platform storybook?

[francinelucca]

what release should we mark this? is this v1? @mattrosno @kingtraceyj @aubrey-oneal 👀

[mattrosno]

@francinelucca is this for our testing purposes? If so, can this live in Storybook?

Or is this for contributors to help them troubleshoot why their content isn't rendering?

[francinelucca]

@francinelucca is this for our testing purposes? If so, can this live in Storybook?

Or is this for contributors to help them troubleshoot why their content isn't rendering?

@mattrosno the latter! it's a list with all the common errors that can appear on the remotely loaded content and some guidance on how to fix

[mattrosno]

@francinelucca this looks nice in the website and I can see how this could fit in the Contributing section. I'm just thinking about how all MDX documentation to browse available MDX components, to copy/paste code snippets, etc. is in Storybook. Would we want this documentation to live alongside the MDX component docs in Storybook? This entire page of markdown could be a story that live in a "MDX / Troubleshooting" section in Storybook, if we want.

Just throwing out something to consider. @aubrey-oneal

[mattrosno]

An example of how docs can live in Storybook is Carbon Charts. It has a top "Docs" section with getting started content. We could have a top Docs section for getting started, but also help content like this, as well.

https://charts.carbondesignsystem.com/?path=/story/docs-getting-started--vanilla

[kingtraceyj]

we think this should go in storybook.

[mattrosno]

Hey team! Please add your planning poker estimate with Zenhub @alisonjoseph @francinelucca @jdharvey-ibm

[mattrosno]

We'll re-evaluate after @jdharvey-ibm adds tasks.

[kingtraceyj]

Here is the Figma for the documentation pattern: https://www.figma.com/file/WyfqQh9R1VXYZErfmsNDVH/Platform_MDXerrors?node-id=317%3A11967

one note i forgot to mention in our meeting—would it be possible to have the examples on white rather than a darker grey?

[jharvey10]

@kingtraceyj Yeah, we can definitely do them on white!

[francinelucca]

Issue to put page in SB: #1430