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

 * 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.
 * Atomic Web Design
 * Anchoring Your Design Language in a Live Style Guide, UX Magazine
 * A list of existing libraries.
 * 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.

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.
 * 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.