Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Revamp the OUI documentation #686
I've started to work on a revamped version of the OUI documentation to address the feedback UIE have received from engineers and designers. This issue exists to point out the problems with the current documentation and share the proposed solutions.
Problems with the current documentation
@daverau-optimizely and I have found the following problems in the OUI documentation from talking with engineers, designers, and using it ourselves.
Many of these issues can be solved with changes to our documentation infrastructure, navigation, and a bit of refactoring.
These are the main initiatives we’d like to tackle.
Component-first documentation with individual component pages
Most of our navigation and performance issues are caused by:
The updated documentation will list all OUI components (and subcomponents), regardless of language, at go/oui. Clicking on a component will take the user to documentation specific to that component. Components available in both Sass and React will have links to documentation for each version of that component.
The simpler layout will make it easier for the user to focus and find the component they are looking for. If we find that we need to make further improvements we can explore adding an intelligent search box that understands component aliases (“alert,” for example, should show results for the Attention component).
The landing page at go/oui will also have links to documentation pages specific to our trump classes.
Combine React and Sass documentation
Our Sass documentation infrastructure lives in a separate repository that must be deployed manually each time a new version of OUI is released.
We will be unifying the Sass and React documentation infrastructure to ensure that the documentation is automatically deployed with each release.
This unification will also enable UIEs to use the Sass documentation as their development environment when working outside of React. This will lead to higher quality components and documentation with fewer mistakes and more complete examples.
Store language agnostic variables as Design Tokens
Our colors, font sizes, and other design-related variables are stored in Sass files. These design tokens will be pulled out of Sass and stored in JSON, Yaml, or a similar file format that can be ingested by both the Sass and our documentation website.
This will make it significantly easier to document colors, font sizes, and other tokens.