Digital projects thrive in the chaos of creativity. But they can only survive with clean documentation and rigid maintenance
Design Project Documentation: Tips, Resources & Best Practices
In the past I’ve covered how to use styleguides on the web and how to publish them live for the world. But in this post I’d like to delve into the subject of what constitutes great style documentation.
This can include a style guide but also includes documentation for written copy, branding, and essential UX components that ultimately make up the user experience.
Great Docs Speak To Everyone
Documentation should be easy to consume yet detailed enough to follow without any prior knowledge. Great design documentation should care about the miniscule details like pixel widths and RGB/Hex color values.
But it should also portray a broad picture of the overall design. It needs to communicate how the design should look, feel, behave, and ultimately be composed on the screen.
You can use design documentation as both a selling point and a communication tool for your vision. This is incredibly useful when you work in a team but it’s just as useful on your own projects.
You can always come back to design documentation to refresh your memory about the goals & objectives of a certain project. It’s also great for new designers who join a team and need design guidelines to add new widgets or new pages into a site.
Think about Google’s material design project and how far it has come over just a few years. This is a powerful example of design documentation at work.
Anyone from around the world can look over these docs and mimic the Google design strategy. It applies to all interfaces from websites to mobile apps.
But this documentation is more than just a set of rules. According to Wikipedia it’s really a design language used to express ideas visually. Great documentation should aim to create a design language.
It should be able to express any idea visually and cover enough depth so that nobody is left guessing how to design a new icon or custom UI element.
If you’re looking for examples check out DesignGuidelines, a new site dedicated to curating online design guides.
But it doesn’t take many examples to pick up the basics. Any great design documentation should be intuitive, easy to read, and simple to understand.
Everyone from the creative team to the higher-level executives should be able to understand the creative direction just from looking over a project’s design documentation.
Starting With Style Tiles
When you’re in the early phases of a creative project you need to get ideas down and see how they fit. Style tiles are the perfect resource for designers to organize a series of colors, patterns, logos, and UI elements together into one place.
This may be considered a type of design documentation but it’s also a powerful resource in the early stages of a new site(or a site redesign).
Check out this guide explaining the basics of style tiles and how they apply to the web.
There are no specific rules and the ultimate goal is to share an overall vision of the design including typography, colors, patterns, and maybe sample widgets like a navigation menu.
This may seem like extra work but there are plenty of reasons to start with style tiles.
- Quicker & easier to create from scratch
- A visual form of rapid prototyping
- Demonstrates the “big picture” of the design
Also remember that a web project may have different phases of the design. The first phase might be identity & branding followed by the interface.
In this case you might create different style tiles for different phases, then expand the tiles into detailed documentation once you pick one.
For example Foursquare has an entire brand book just for their logo and icon.
This PDF includes design guidelines for the logo, the icon, and some of the badges created for Foursquare users.
Style tiles should be much lighter than a brand book. However the inspiration for a style tile can ultimately funnel into a detailed brand book or UI design document.
Use these to your advantage during the early phase of a creative project. Once you know which design style is a winner you can flesh out more detailed ideas.
And to learn more about style tiles check out some of these related posts.
- Style Tiles: An Alternative to Full Design Comps
- Style Tiles and How They Work
- Free Style Tiles Template
Deliverable Style Guides
Web projects rely on style guides just as much as any other design project. These guides are the final “polished” documentation for UI designers to study and replicate.
Google’s material design is one example of a free open source design doc. It tells designers how to style buttons, tabs, and other widgets. It also delves into animation effects and how a material layout should “feel” when the user interacts with the page.
Before you start a new style guide you should consider what you need to cover.
There are no specific limits but you should consider a variety of topics:
- Primary/secondary/tertiary colors
- Typographic styles and font choices
- Background patterns
- Button designs
- Icon styles with examples
- Forms & input fields
- Wireframe flows
Remember you want to capture the big picture of the design while also documenting all the little details from button sizes to font styles.
This guide will become the design documentation for whatever site you’re designing. As you craft the design try to break up elements into sections that you can use for a table of contents.
For example, you might have one section on typography and another on buttons or form inputs. A designer should be able to skim through your documentation and quickly find whatever they need.
In many cases it’ll be better to create design documentation as a PDF along with a webpage. This page can be private for internal use only, or it can be public and shared freely.
Take for example Mozilla’s style guide webpage.
This certainly isn’t the most detailed style guide but it does cover a lot. You could use this as a basis for starting your own documentation while adding sections as needed.
Keep in mind that mobile is on the rise so you should document any specific details for the responsive layout. Do headers need to be resized? How much padding do you need on buttons?
It may seem annoying to get into this much detail but designers who pick up your documentation will be forever grateful.
Capturing The User Experience
Style guides are basically the de facto solution for design documentation. They can cover an entire interface full of elements, colors, and basic style choices.
But a much newer aspect of design documentation is user experience, and I think this will become even more important as time goes on.
The normal design docs include colors, spacing, fonts and icons. But you also need to consider how the interface behaves and how it should operate.
Do you have any CSS/JS animation? And how are those interface animations created? What sort of easing and timing should be used? What about page flows & interactive elements like forms?
Don’t be afraid to add far more detail than you might think would be useful. This extra layer of info can be an asset to future designers.
For example, adding a wireframe that displays the user flow between pages can help creative directors explain the “big picture” of the project. Executives can determine if they have all the necessary pages on the site while designers can plan where other pages should go.
If possible you should always provide a top-down view before getting into the nitty-gritty detail. If you can learn to make documentation for everyone you’ll realize the importance of all the big picture stuff.
“Animation absolutely belongs in your style guides. It’s the perfect place to document what animation decisions have been made, and to lay a foundation for making cohesive animation design choices in the future.”
Val mentions the example of IBM’s documentation which has a separate page for animation.
Companies big and small can benefit greatly from adding user experience concepts into design documentation.
Interfaces are built to be touched and clicked. So it could be argued that the experience actually matters more than colors or font choices.
But if you’re able to work with both then pad out your docs and go for detail. There doesn’t seem to be any limit of “too much” information with a style guide.
If it’ll help future designers understand and expand upon an existing design then it probably belongs in the documentation.
The first time you create design documentation it’ll feel awkward. You basically know what to do, but the actual structure can be overwhelming.
I find it’s best to create and finalize the design irst. Once it’s signed off you can take notes on paper(or digitally) listing ideas for documentation chapters and important sections. Break this down further until you have a sturdy outline for the documentation, then start chipping away!
Design documentation isn’t perfected the first time around. You have to practice to fully understand what your clients need and what you should deliver.
Try practicing with existing websites first just to build up your skillset. From there you’ll learn what works, what doesn’t, and how to craft a completed design doc from scratch.
If you’re looking for more detailed information about creating design documentation then you might enjoy these related blog posts:
- How to create a web design style guide
- Brand Style Guide Examples
- Front-end Style Guides
- How to write the perfect Website Specification Template
Featured image: brand manual template.