design icon indicating copy to clipboard operation
design copied to clipboard

Skunkworks 10/23 - Docs Redesign

Open spark33 opened this issue 5 months ago • 0 comments

This PR implements a redesign of our component documentation pages on .design worked on by me and @sooachung over Skunkworks in Oct 2023.

image

The PR introduces several new features including:

  • Support for authenticated content pages
  • New design that replaces tabs with a single scrollable interface
  • Sticky breadcrumbs to better support the scrollable interface
  • Support for a new LiveExample block content type on Contentstack that will allow us to insert LiveExamples into our design guidelines
  • Support for a new image gallery content type on Contentstack
  • Support for code blocks for each storybook function definable in the function's parameters
  • Integration with the experimental branch on Contentstack, which can be used in the future for similar blue-sky changes to .design

As presented in my Skunkworks demo, these are the visioned benefits of this change:

  • It allows us to document our components in a use-case driven way in an attractive and user-friendly interface.
  • All information on our design system lives in one place.
  • Everyone gets their questions answered before they have to come to us on Slack.
  • They get to just enjoy the visual sexiness of the new design!

For maximization of the updates made here, I recommend updating our design guidelines on Contentstack to resemble the guidelines for TextInput on the experimental branch of our Contentstack instance. This is an example guideline that Sooa and I have created to demonstrate how powerful these new updates can be.

Other changes that would help make the most of these features are:

  • To migrate the LiveExample content type from the experimental branch to main on Contentstack.
  • Add code snippets to its parameters as demonstrated in this PR
  • Migrate the TextInput component documentation from the experimental branch to main on Contentstack.

Not making the above changes and merging this in would still ensure the layout changes and breadcrumbs are added to our website. If I were around to help push this through, I would've gotten this PR reviewed, then applied the above changes, and then asked our users for thoughts on the new guidelines format proposed with the TextInput guidelines. IF feedback was positive, then similar changes could be made to other components moving forward. If the changes were applied, it would be best for engineers to get in the habit of contributing to guidelines as the goal of this initiative is to combine engineering docs with design docs.

-- The LiveExample content type on Contentstack works by identifying stories on Storybook by function name. For example, the States Demo story on Storybook is defined by the function StatesDemo in the Storybook file, and that's what should be populated in the LiveExample entry on Contentstack.

--

Aspects of this PR I consider a little incomplete are:

  • Code style
  • Reliability/accuracy of the scrolling breadcrumbs
  • Error catching on LiveExample blocks

This PR would also address the following tickets:

spark33 avatar Jan 09 '24 04:01 spark33