Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Skunkworks 10/23 - Docs Redesign #340

Open
wants to merge 12 commits into
base: staging
Choose a base branch
from
Open

Conversation

spark33
Copy link
Contributor

@spark33 spark33 commented Jan 9, 2024

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:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant