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

Revamp the OUI documentation #686

danoc opened this Issue Dec 10, 2016 · 1 comment


None yet
2 participants
Copy link

danoc commented Dec 10, 2016

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.

Navigation Issues

  • Sass and React documentation are separate. This leads to a frustrating user experience since we haven’t reached parity between Sass and React components. More importantly though, OUI provides a number of helpful utility (“trump”) classes that are only documented in Sass and are helpful even to developers working with React. There is also no link between the two documentation pages.
  • Sass documentation is slow because there is too much in the DOM. This happens since we display all of the documentation on one large page.
  • Sass documentation has confusing whitespace because it displays information from all files, even those that don’t have meaningful content.
  • Component names are not always intuitive making it hard for the user to find what they are looking for.
  • React documentation becomes harder to navigate as more components are added. This happens because the documentation is a single page, the navigation is not sticky, component code examples can get long, and component names are not always obvious.

Missing Content

  • Icons, colors, and font sizes aren’t documented in either documentation site. This is a huge pain point for designers that want to reference the styles and engineers that want to find the classes to implement them.
  • Sass documentation isn’t quickly deployed when new versions are released. This is because, unlike the React documentation, the Sass documentation infrastructure lives outside of the OUI repository and is not part of an automated build system.
  • There are missing examples in Sass documentation. This likely happens because it is very hard to view the examples in the OUI codebase.
  • React OUI sub-components are not documented, making components like Table hard to use.
  • There are many components that don’t exist in React and there is no link to the Sass documentation for those components.

Incorrect Content

  • Examples in Sass documentation don’t always work if they require JavaScript. We once wrote JavaScript to power a handful of our components, but the JavaScript depends on jQuery and hasn’t been adopted outside of the OUI documentation examples.
  • Examples using JavaScript don’t work in the Optimizely codebase:
    • The components that require JavaScript use Vue.js in Optimizely but jQuery in OUI. This makes it hard to write examples that work for both.
    • The Optimizely app uses a lego- prefix while all other projects that use OUI don’t have a prefix. (More about the prefix issue.)
  • Components may look different in Optimizely X due to CSS overrides that exist in v2.css.

Proposed solutions

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:

  • Putting all of the documentation on one very long page.
  • Choosing a language (Sass or React) before knowing which components are available in each without a clear path back to the other language.

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.

Remove JavaScript from Sass examples

Some of the components in the OUI Sass docs (dropdown, disclose, accordion) are only useful with JavaScript. This has always been a problem because Optimizely’s codebase wraps these components with Vue.js directives and components, an implementation is difficult to replicate in OUI’s Sass documentation. This meant that the JavaScript interactions within the examples in the Sass documentation didn’t work.

We made the examples work by writing JavaScript to power the components, but:

  • We don’t believe it is being used outside of the documentation.
  • It has created a false expectation that component will “just work” when copying and pasting code into Optimizely.
  • Some of the examples are broken and fixing it is not high priority enough.

We’ve started to create React components for OUI that do “just work” once copied, so we’d like to remove the JavaScript from the Sass examples add it back in the future if we find a need.


This comment has been minimized.

Copy link

danoc commented Jan 18, 2017

This is being tackled in #692.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment