How can we improve the documentation site UX

[andrew-codes]

What are some ways to improve the UX of the documentation site and, hopefully, get rid of the need to have a separate storybook site?

[andrew-codes]

Here are some thoughts to spark conversations:

Streamline Navigation

Simply navigation. It should be optimized to allow components to have a large number of example code snippets (storybook stories) that are easily accessible by name in a menu.

Main Navigation

There are three use cases that should be visible at all times; going to the homepage, searching, and on-demand access of the main navigation. These should be icons as the menu should likely be vertical in nature; see the second bullet beneath the first bullet below for reasoning.

• search expands a pane to enable text input as well as room to display the search results
  • effectively removing the dedicated page for search results, which seems clunky and dated
  • a vertical pane is chosen to optimize display a search result list which is ideally displayed vertically
• hamburger menu would shows on-demand, top-level navigation items (not in correct order)
  • license
  • Guidelines section
  • VersionOne UI section

Guidelines Section

This section describes our user experience patterns, styling choices, and guidelines. This includes everything from defining color meaning and intentions to icon standardization in shape, form, and color. It essentially is our style guide and patterns that shape and "guide" our UX.

VersionOne UI Section

This contains information on how we have implemented our Guidelines (above). We should be capable of viewing prior versions of the documentation details for any given component.

• how to get started with using library
• listing of links to all the components in the library
• Link to library's github repo
• contributions guidelines
• changelog

Components could also be grouped by the pattern they fall under and should at least be search-able by pattern.

Component Information

Every component should include basic details about itself; name, version, description, and possibly links to all patterns from the guidelines that it explicitly implements. They should also be search-able.

A component's props should be listed, their type/shape, their default values, and a description of what they represent. This essentially provides consumers with the API of every component.

Each component needs navigation room for many examples. Each example is named and should contain a link in some navigation form to provide easy and direct access to it from the component page. Examples include a short description, a code snippet and the output of the code snippet. Snippets should be live. In other words, they can be edited and their output is immediately preview-able in an output pane. Snippets require a great deal of real-estate and, when selected, should be the main focus.