Comparative Analysis
In order to gain a better understanding of what’s currently out there regarding pattern libraries, style guides, and front-end framework documentation, a comparative analysis was performed. This analysis targeted 8 “competitors” including a few of the most widely-used, well-established frameworks. In addition to the most popular, some guides were included in the list that are not as well known, but are quickly gaining momentum in the category and should have something to teach us.
By examining the strengths and weaknesses of the various implementations by the related websites, we were able to uncover insights about what types of patterns can be adopted as well as what should be avoided. This helps us to make informed design decisions.
This comparative analysis focused on 3 main heuristics to evaluate against: Aesthetics, Ease of Use and Help and Documentation. Each of these categories was broken down even further into subcategories specific to style guides which included Navigation, Code Snippets, Showcase, Accessibility, Staying up to Date, and Getting Started.
Below are the final recommendations that were revealed through performing the comparative analysis. For additional information on how these recommendations were created, please refer to the key findings and comparative analysis spreadsheet.
- Break the content into smaller “bite-sized” chunks where the extra context is there for those who want it, but those who don’t want it, won’t have to read through a paragraph to find just a single thing
- Use bullet points and highlight key words to help with scanning rather than large paragraphs
- Use colors with high enough contrast for headers of collapsed sections so it’s obvious there is more to see there rather than low contrast (light gray on white). This also helps with differentiating where a new section begins
- Use interactive examples where users can test out functionality for themselves such as sliders, checkboxes, dropdown menus, etc.
- Add a copy link in the code block areas to allow for quicker workflow
- Option to add the copy link to appear when you mouse over the code area (MDL does this cleanly)
- Be careful not to cover up sections of the code with the copy link
- For more complex code, add a CodePen link where users can test out code real time before committed to implementing it
- Consider using a darker background for the code section (something other than white) so the code area is better differentiated from the rest of the content on the page (MDL and Angular are stellar examples)
- Option to use familiar code editor theme colors such as Sublime Text for the code snippets
- Place code samples close in proximity to the relevant visual example
- Add CSS and JS code samples where applicable
- Should continue using the sticky left nav for the components and using the top nav for the main, more general items
- Should continue using the nesting in the left nav where necessary for organization and ease of access
- Add an FAQ page that proactively addresses the top questions that come up (or could potentially come up)
- The FAQs should address topics such as customization, browser support, government-specific information users might need to know, how to report a problem, etc
- Having FAQs could potentially save time in the long term with answering support emails about common questions
- Add a showcase section where users can see what the final product could look like before committing
- Consider adding real users’ testimonials in order to build confidence for potential users
- Consider adding customization option with a theme builder for users who want to try out other color schemes
- Add starter templates that includes HTML, CSS and JS with examples showing what the layout with color could look like
- Consider adding a “How do I start?” section for beginners with links to CodePen, tutorials and a starter project
- Add the supported browsers/devices for the framework. Using a table is a clear way to display what’s supported and what’s not so users can scan it quickly
- Show the latest version number on the top of the page in the nav or on bottom of the page and link to where previous revisions live in GitHub
- Encourage users to sign up for mailing lists to receive updates and use Twitter for sharing news relating updates
- From the nav, link to relevant blog posts about updates to the WDS informing users about what’s new, how they get it, and any potential issues that they might have if they update