Design/Living style guide/Requirements

This is an initial draft requirements document for Wikimedia's Living Style Guide. It's mostly some notes for Andrew.

Previous work

Currently, Wikimedia has two "Living Style Guides":

• We have a styleguide automatically generated from our LESS using kss-node. This styleguide is pretty, but it's focussed around documenting our CSS (notably, it doesn't document our OOUI widgets), and it still feels quite 'static'.
• We have an OOUI demo page which gives us a bit more of a dynamic feel, and shows us OOUI widgets correctly, but doesn't document our CSS, and doesn't allow us to put more 'tech writing' type of content in (i.e., content not directly related to a specific widget, but about general principles.

Inspiration and work by others

Articles

• Atomic Web Design
• Anchoring Your Design Language in a Live Style Guide, UX Magazine
• A developer from Lonely Planet discusses why CSS-driven style guides don't make sense

Existing Living Style Guides

• Google's Material Design Guidelines are excellent.
  • They are nicely designed themselves.
  • They include copious examples.
  • They are easy to navigate.
  • One problem: there isn't any discussion of implementation; however, there is the Polymer Project.
• I don't really like GitHub's style guide (generated with KSS).
  • It's very implementation-specific, yet doesn't really give clear implementation steps.
  • It's not very well organised (there isn't really a sense for what's important and what isn't)
  • There's no overarching structure or tech writing that tells us anything about GitHub's philosophy or architecture.
  • It doesn't feel complete.
• Mozilla's is okay.
  • It's easy to navigate
  • It's dynamic and has plenty of examples.
  • The amount of tech writing is variable. The Firefox OS section has plenty of justification, the Forms page under Sandstone gives you a list of labelled form elements and that's it.
  • There's no information about implementation.
• I really like MailChimp's styleguide:
  • It's easy to navigate and pretty.
  • Almost every example is accompanied by code.
  • It has explanation of the history and vision behind the framework.
• Lonely Planet's styleguide is a good example of a component-driven style guide, and seems to be flexible enough for our needs.

Existing Style Guide Generators

• https://github.com/hagenburger/livingstyleguide
• KSS
• Pattern-Primer
• StyleDocco
• Style Guide Boilerplate
• Pattern Lab
• And lots more

The general approach of most of these libraries appears to be: Create HTML/CSS/JavaScript for each individual component. Document the component, either in the CSS file using MarkDown or in a separate file in the same directory. Add some other MarkDown files somewhere or other (not all frameworks support this).

This is difficult for us as we're using a JavaScript widget library, not plain HTML/CSS/JS. Perhaps we can figure out how to fake it, but we really want to draw these items with OOUI's JS or PHP frontends, not by providing example HTML / CSS. I want to investigate these options to see if their architecture permits plugging a different data source in.

Goals

Our living style guide should be:

• Living. It's okay to take sections and tech writing as external input, but the documentation about OOUI components would ideally be generated dynamically from the same code that runs the website. If it needs to be maintained, it will get out of date.
• Structured: We don't want to take the approach of just documenting each widget in alphabetical order. Our widgets should be grouped logically, and we should be able to write information that explains what this group of widgets is intended to achieve, and when each one is appropriate.
• Flexible:
  • In addition to documenting widgets, we also want to add documentation about our CSS classes, for example, as well as general documentation about our design philosophy.
  • Aside from documenting user interface elements, we should also show example usages
• Maintainable: Our designers should be able to update our living style guide without needing to edit text files / go through code review processes.
• Dynamic: We want to render the elements themselves using OOUI. As a stretch goal, it would be awesome to be able to change options, such as settings, CSS classes (e.g. constructive, destructive, etc), and have the code update itself.
• Accessible: We want our living style guide to be useful to lots of people. This entails:
  • Providing working code for engineers to use right away.
  • Providing interactive demonstrations and examples, along with explanatory text.
  • Easy to digest non-technical users with little to no knowledge of code to understand and use the existing styles.
    • As little words as possible to be precise
    • Layman language as much as possible (we have a wide audience)
    • A good balance between code and design presence in the document so non-technical users as well as technical users can feel familiar and comfortable with the content

Development Principles

In developing a solution, I want to follow the following general principles:

• We should take advantage of existing code. I'm loathe to reinvent the wheel. If there is existing, tested, working code that meets our requirements, then we should use it rather than building our own castles.
• Our code should follow existing common practice as much as is sensible. This means that even if we do go our own way, we will be able to leverage existing code in the future.