Update code documentation template

[mattrosno]

There have been questions on why we need a code tab, as it seems like we're using Storybook for API documentation and using the Overview tab for the live demo and to link to other frameworks. Here are a few scenarios to consider:

Scenarios

1. No code tab (design-only assets)

This will be the case for a lot of the patterns.

2. No code tab (because one hasn't been created or indexed)

This will be the case for a lot of non-React and PAL components (because there aren't legacy Code tab content to initially use.)

3. Code tab with content that primarily links to external API documentation (e.g. Storybook)

The Overview tab has link(s) to demo site(s), and a live demo, but is that enough? What if there is additional documentation that lives in GitHub that we want to point people to?

I like the idea of having a markdown page for code even if it's minimal, so we have room for asset maintainers to document whatever they see fit, even if that's just a page of resource cards that take you to:

• Storybook sites
• GitHub documentation

4. Code tab with developer documentation

Another reason to keep around the code tab is for if (when) we standardize the elements markdown pages into foundational libraries and assets so this content would live in code tabs:

• https://carbondesignsystem.com/guidelines/2x-grid/implementation
• https://carbondesignsystem.com/guidelines/color/code
• https://carbondesignsystem.com/guidelines/icons/code
• https://carbondesignsystem.com/guidelines/pictograms/code
• https://carbondesignsystem.com/guidelines/motion/code
• https://carbondesignsystem.com/guidelines/spacing/code
• https://carbondesignsystem.com/guidelines/themes/code
• https://carbondesignsystem.com/guidelines/typography/code

Another thing to consider is how libraries like IBM.com Services uses JSDoc. For example the AnalyticsAPI asset has this for indexed externalDocsUrl: https://carbon-design-system.github.io/carbon-for-ibm-dotcom/services/AnalyticsAPI.html

The content for this external documentation site is automatically generated by taking source code and source code comments and building a docs site from that. Pros: you just add it to your build process and have minimal configuration. Cons: it's not versioned, and separate from any other library-level documentation like maintainers, and you have to host it somewhere.

If IBM.com Services didn't want to host a JSDoc site for this, they could customize their build so JSDoc information got written to the code.mdx file for each asset. Doing so would allow this content to be versioned via Carbon Platform, and they wouldn't have to host anything.

This is a stretch and I don't expect this to happen, but having a code.mdx page tab is nice because it gives our maintainers optionality to populate it however they see fit and as long as it's valid markdown and MDX, our platform can host it.

Acceptance criteria

• [ ] Code docs template has been reviewed by the system squad
• [ ] Create an asset overview page markdown template that includes the "Live demo" heading to assist consistency

[mattrosno]

Hey team! Please add your planning poker estimate with ZenHub @aubrey-oneal @kingtraceyj

[jeanservaas]

@mattrosno @alisonjoseph I don't think we need a code tab now. We have no dev docs on it for the most part for any carbon components. When we start to add docs, or content starts coming in from PALs, we can make a case to add it. But I'd like to avoid a bunch of empty pages until we have content.

[mattrosno]

@jeanservaas we need a code tab. A lot of the PAL components and patterns have code tabs. Yes some just link to Storybook, but others show code status tables and detailed documentation. Some examples:

• https://pages.github.ibm.com/ai-applications/design/components/color-picker/code
• https://pages.github.ibm.com/cdai-design/cloud-pal/patterns/email-templates/code
• https://pages.github.ibm.com/cdai-design/cloud-pal/patterns/provisioning/code
• https://pages.github.ibm.com/cdai-design/cloud-pal/layouts/world-level-layout/code

[mattrosno]

But I'd like to avoid a bunch of empty pages until we have content.

@jeanservaas if you don't want minimal code tabs for Carbon React components, then we don't index a codePath for those components, and the asset detail pages for those components will have no code tab.

[alisonjoseph]

@jeanservaas like Matt said, unless we specify a codePath and code file for a particular component the tab won't show up, so we can easily avoid having empty pages. (agreed that we don't want empty tabs)

[jeanservaas]

Sounds good on the code tab. Not sure who would author this MDX template though. It seems like this is more of a dev issue since dev understands the content that would/could comprise the MDX template.

Also having MDX templates for all of these tabs would be great, but we've been operating without an MDX template for Style for years... it needs to be done, but maybe not a v1 issue.

Also, we're going to look to @mbgower for the accessibility template.

[mattrosno]

@jeanservaas sounds great I'm going to remove the estimation and design label and convert this to a dev issue to do.