Style guides - Documentation or Workbench?
Brad frost has posted something about styleguides that I find really illuminating: http://bradfrost.com/blog/post/the-workshop-and-the-storefront/.
He talks about the difference between the place where you work and iterate to create the output, and the place where you show that ouput off to the users. This seems obvious now that I see it, but it was foggy until now. When we become styleguide producers or design system designers, then we need to think about shifting the process back one more step. Sometimes we produce a system for a large organization (or the public) to use and that sytem has to be really clean and well organized and the documentation needs to thorough, maintainable, attractive and usable. But, we still need a place to build those design components and test them iteratively without commiting everything fully to JS or back-end coding.
The patternlab tool that I grew to love during my first styleguide project has not been the my final choice for the last two style guides. This has been for a couple of reasons, but mainly because I needed something that would integrate tightly with an existing web app codebase. This would help keep the patterns up to date with the actual production code more easily. And one thing I especially love about design systems is that developers can grab a copy of it and do rapid front end dev without needing to run the full development environment and incur the time delay that comes from the extra overhead.
This all leads me to a place where I was creating style guides that are both workshop and storefront in one, they were supposed to be a place for collaboration and iteration amongst developers and designers, but they also needed places for lots of documentation. This lead to a hybrid construct where static documents were being combined with component modification workspaces. On my most recent system the dev team had already built hundreds of React components, and the scss files were being loaded directly in the coponents. Now instead of trying to force them to rearchitect all of their SCSS and make them convert React components into mustache templates for patternlab I looked for ways to convert them automatically. I tried this project on github and I even tried building my own grunt task that could do it, but I realized it was just becoming too disconnected from the original JS codebase. So I went back and found a project called React Styleguidist which they call a “component workbench” (see!) that was just right for that use case, and I was easily able to extend it to serve a custom layout and create extra documentation pages using static markdown files.
So far, combining a “workbench” with a documentation site has actually worked out well for these smaller systems, but I saw immediately what Brad was talking about with the need for separation and abstraction when these systems get bigger and have bigger audiences.
Our understanding of the needs of our users has to shift from the end-user to the internal developer and designer when we make the shift to becomeing system designers. And I encourage you to think about the needs of your users carefully every time you start a new style guide, think about the technical advantages and disadvantages of all the tools out there and dont be afraid to get your hands dirty and create something new and unique for the needs of each company or team.