Jan Persiel's Blog

When style guides are documentation done wrong

Introduction

Jan Persiel

Jan Persiel


styleguides documentation workflow

When style guides are documentation done wrong

Posted by Jan Persiel on .
Featured

styleguides documentation workflow

When style guides are documentation done wrong

Posted by Jan Persiel on .

If you would ask me which topic I would recommend to get an article written up for your blog which people might ignore right away I would probably think for a moment and recommend something like "anything about documentation" along with half a dozen other topics as well I guess. So why the heck do I write about documentation then? Hear me out:

Documentation sucks

Coming from a design background I have been in the documentation business from the very beginning. We designers are awesome at documentation. No, really! We call our documentation efforts style guides and brand manuals. Oh boy, are we good at those. We can create documents which are several hundreds of pages long. They scare the s**t out of a clerk working for the EU in terms of extensive coverage. We are leaving nothing to chance. We tell people how to position logos, re-create letterheads, use pictures and how many pixels there need to be between the third and fourth menu item on a mobile website.

I love to hate you

So we love these documentation efforts, or don't we? Actually no. We hate them quite frequently. Everyone who needs to work with a style guide hates them most of the time. But why? We create them so often that we should be more than happy to get one in front of us. As a matter of fact, it is no surprise: They are hundreds of pages long, they tell you down to the pixel how everything needs to be, … okay I have talked about it earlier on. Now what exactly is the problem then? Are all designers bi-polar freaks? (Some actually are, and they even need this to come up with the great ideas, but keep calm, it is only very few of them). We create them and hate them as soon as we need to use them? That sounds like a classical case of Do-as-I-say-don't-do-as-I-do.

Precise, but not helping

The problem with the afore-mentioned style guides is that they are often times super precise in what they describe. They meticulously tell you how business cards are supposed to be "designed", but they often times lack a clear description to tackle a new problem which no one has worked on before.

For that very reason it turns out to be a pain to read style guides most of the times. Do not get me wrong: They give you a good idea about what the general idea about a corporate design is. But who in their right mind wants to wade through pages of stationary design guidelines when your task is to design a website or banner.

Instead of writing a documentation which actually helps someone to work on or with the design, it is not seldom to find a poor trainee tucked away in the basement of some design agency working through the endless layouts and things which were created before, only to "enhance" PSDs with website designs and Illustrator files with stationary designs with measurements.

Fire and forget

Guess what, the(se) style guides are barely respected by anyone, really. They are deliverables and are outdated the moment they are being exported from the authoring program. No one wants to update them later on. The process to create these shiny objects of design documentation in full PDF galore is tedious and annoying. Where does the thing live and come from in the first place? Does the brand agency hand over the open files for the style guide so that employees of the stye guide's company can update them? I bet you they do not in most of the cases. So the thing is that even when new stuff gets created, it will most likely not end up in the style guide. Maybe a new one gets created because no one can edit the original document. The web style guide for instance. Great two documents now. Both waiting to be outdated.

And even when the agency in charge of documenting the brand does take care of the document and keeps it fresh and updated, there is the problem of the old versions still floating around on peoples hard drives and external suppliers servers. I have never ever encountered a brand book ever with an expiry date. And that would be the only way to communicate that you are using a wrong documentation PDF.

No documentation? Sucks as well.

So what is the solution? No guidelines at all? Definitely not. We all want a design and brand to be consistent. There are many people out there who have no idea about how things should and have to be in order to maintain a visually consistent appearance. And to be honest with you they do not have to. That is what the designers and people in the design role have to take care of.

But how can we avoid being in the position of having a documentation but not getting the information we need to know? We have to ask ourselves what it is that we need from such a document. Do we need the stationary x-rays? Do we need the distance measured in pixels between menu items? And even if we get the information we need: Do we have the tools to follow the guidelines? Or whom do we have to turn to?

What do we want from a style guide?

First of all we need to understand that these manuals are being read by different people with different assignments and tasks to be completed.

There are designers who know their stuff. They will roll their eyes when you bombard them with the measurements of the letterhead. What an idiotic idea to document this anyway: Someone creates a letterhead, another pour soul has to measure everything and write it on a layer above the design, create a PDF and share it, only for a third person down the documentation chain to read the measurements and recreate the document. Whoever creates things like this is guilty of wasting gigantic amounts of resources and employee happiness. You get the point: Why on earth would you not pass the original template to the designer who needs to update the letterhead or create a new one for the branch in Milan, Italy? Yes, no sane or non-money-making reason here. So, make the templates and assets connected to them available and write a quick info about what should be paid attention to when one breaks the current proportions or text amounts change and break the layout. And a quick word to those agencies out there who do not release open documents and files to clients because they want to gauge them every time they need more letterheads or new business cards for new employees: You can do better than that. What a pitiful way to make money, holding your clients documents ransom. Is that what you wanted to do when you started your company? Wouldn't it be better to do more design work and convince your clients to invest in more design rather than a new box of letterhead A4 sheets? Yeah, that's what I thought. (Sorry little side-beef here. Back to the main topic …)

Then there are project managers for instance. They might hire an external software house to get a new application developed. What do they need? They need something to pass on to the designer and/or front-end person to create an interface that matches the brand guidelines. But how can they do that when there is a style guide for the marketing website which does not feature many UI elements needed in the application? They need these UI elements and a direction on when and where to position things. Furthermore there should be something on user flows and what it should feel like. They would be a lot better of with a style tile in many instances than with a micro-measured style guide page about the homepage of the marketing website.

A document like a style tile or a description with general UX principles helps to understand the reasons and ideas behind a design philosophy, the design system and the values to communicate. And that is exactly what people need: They need brand guidance and not asset assembly plans. A brand is not a concrete structure, it lives and breathes. When you put it into a rigid suit of armour it will be stiff and not fast to respond to changes and requirements.

So you should ask yourself these questions when creating guidelines, brand manuals, and style guides:

  1. Who will read this document? What do I need to explain and what is to be neglected in order to keep things short and precise?
  2. Which tools do they have at their fingertips to achieve the results?
  3. What is the idea and reason behind this? With this knowledge it is easier to come up with a plan b in case one cannot recreate the solution chosen in an earlier implementation.
  4. What are we trying to avoid? This is not the typical list of examples of how not to position the logo (although these are helpful from time to time) but an idea to support the reader of the guidelines in where the company does not want to go because it might be the competitions terrain. This last point is completely optional and might not always make sense. It is actually covered by number 3 implicitly when done right.

Paying attention to these questions will dramatically improve the usefulness of such documents and make them more readable and worthwhile.

When is the right moment?

So when do you write these things down? I think I made it clear that this is no job to be done by the trainee afterwards. If you are serious about making this a living brand and a useful document you as the creator should write it while you work on it. If things change, change the documentation. Only when you capture the ideas right away you will not miss a thing. This is true for all kinds of things, be it a front-end topic, a logo positioning, or even the choice of a font.

Web trumps PDF

Even the last person on earth has figured out by now that this is not scenario for a massive InDesign document. We are talking Wiki-style collaboration and ease-of-editing now. Hey, and guess what: When it is on the web or the intranet, well, in a browser, there is a central location for everyone to go to and to look up what they need. No multitude of old and outdated PDFs on hard drives distributed across the planet. There are so many simple HTML generators out there which allow for collaborative work that there is no excuse to use them. The sky is the limit really.

The value of documentation

So is there value in documentation? It depends: As long as documentation is only to prove that you have done some work and is a mere write up of the obvious … maybe. But if the documentation is written in a way that it can actually be used to look things up in order to not just reproduce them but to actually create new things there is a lot of value in every documentation offering that option.

Coming back to the style guides from earlier on in the text there is a definite value as soon as you start creating it in a way that it is user-centric, offers guidance for everyone who needs to get things done related to the brand and anything involving corporate identity and design. And as long as it is kept current.

Getting good with documenting things

Documenting things is not easy. It involves a lot of brain work. Yet another reason I never really understood why the most essential work a brand agency is doing is stuffed into so many flatulent PDFs with just measurements.

When creating and working on things you should document as you go. Actually, start even before that: The idea and the assignment of what you are working on is part of the documentation as well. It usually describes the job to be done. And to document that task is essentially the core reason for a style guide to exist, isn't ist?

As mentioned before: Make documentation as easy as possible. Lower the barrier of engagement, make the tools super simple, make the updates a piece of cake.

Last but not least remember a thing: Keep the documentation open and accessible. Only when everyone has access to it and gets the latest and greatest version of it, they will be able to work with you on getting it better and telling you what they need and do not understand. Only when you get this feedback and work on it, a documentation turns into a living thing everyone values and wants to work with, be it a style guide or a guideline for taking calls.

Alright, that was a tough one. I hope it did not end up being too boring. I always feel passionate about proper documentation and offering useful information, so that is why this topic gets me fired up 'a little'. Take my ideas with a grain of salt and feel free to let me know whether you agree or whether you do not. What are your thoughts on documentation?

In another blog post I am planning to write about documentation of processes. Stay tuned and let me know your thoughts on this.

Jan Persiel

Jan Persiel

http://persiel.com

View Comments...