Documenting Design

Documentation is the single most mundane task in the creative process and there is no surprise that it is ignored, even swept under the carpet at every instance. By definition,  it is the act or instance of supplying of documents or supporting references or records. In essence, confirmation that some fact or statement is true through the use of documentary evidence.  What does documentation have to do with design and why must designers apply the use of this concept and technique in one’s own process of creation? Simply to capture one’s own design decisions for posterity making the creation process easier henceforth. It is important that every step of the process is documented by communicating as effectively and clearly as possible. While the obvious attributes to a good document are essential information and clear writing, one must also keep in mind key attributes:

The Audience

Assuming you are designing for an audience, documentation will then make it’s obvious need felt. In short, if your documentation doesn’t serve the needs of your audience, drop it! Which means first find out who your audience is and what, exactly, it needs. Sometimes you may be documenting the process merely for future reference, making you the audience. So you are writing for yourself. As good a reason as any.

If not, who is your primary audience? Isolate your intended audience or target group and structure your language and content for them. If you must cater to a disparate group of people in a single document, organize it so that each group can read just the section that applies to them, like those product manuals that feature different languages in the same manual. Discover the needs, questions, desires & wish-lists of the audience to get the basic structure, tone and emphasis of your documentation.

Keep in mind the unique culture of your audience. Be aware of how your audience uses documentation. Are they going to use it as a technical manual, research paper, practical lesson or theoretical essay? Will the document be used more often as a print document or would it circulate on the inter-webs alone? Maybe a presentation would make more sense or maybe you want a more comic book format in keeping with your audience’s culture and identity. Such interrogation will reveal who the audience is, what they want and how they’d like to view it.

Spin the story

Through the history of mankind, propagation of ideas and concepts has been through the medium of stories complete with a stellar cast. Right from religion using analogies of characters and their extraordinary tales to communicate the message of goodwill and harmony to royalty patronizing plays that would depict their deeds in a format that would endure the sands of time. In summary, if you want your audience’s attention, tell a story!

Instead of interpreting the document as a well-organized collection of specifications, descriptions, illustrations and diagrams, create a narrative around it which would guide the user through it in a familiar way. While it doesn’t have to be a novel, incorporating certain novel-like elements is invaluable. Scenarios can describe motivations, emotions and goals. Scenarios are especially useful in the early stages of a project, when conveying the value and purpose of the product is key. Scenarios don’t specify what the site or product looks like, or what content is featured on the home page. Instead, it focuses on what’s important to the end-user.

Walk-throughs, on the other hand, better communicate basic step-by-step procedures that explain how the persona can interact with the product/service, each action she takes, and the corresponding response she gets from the system. They explain interface behavior simply and easily to the user. Both scenarios and walk-throughs work best when accompanied by illustrations or screenshots of the design.


Have a main character or mascot and use personas during the design process. The Dummies character is etched in my memory as this triangular shaped Fido-Dido-esque figure with nerdy glasses offering advice, facts and what-not sprinkling my journey of learning with anecdotes. Your main characters for your documentation can have names, backgrounds, preferences, ambitions and goals and refer to them by name to build a bond with the audience. If you are describing how your product might fit into the audience’s requirement, spin a story about how “Mary” benefits from using your product in her daily life. More complex behavior of user interfaces can portrayed in terms of Mark’s actions and reactions. Represent the end user in your documentation in any form – as simple as a line drawing or a rough sketch. But a picture is worth a 1000 words and your description of the target user’s characteristics with a personalized name offers the audience identification.

Defining the Design

Sometimes the user wants to know more than just how a product works and what it looks like. Most importantly people want to know the why? behind the design. Thus it is imperative to provide a means for the audience to embrace the design. This is where personas or product mascots come in handy to make the user experience more pleasant. Such an approach will answer questions even before they are asked.

This will also serve as a pro-active way of showing that you’ve considered the needs of your audience. Describing the design in terms of business requirements puts product managers and executives at ease and reassure programmers. Offering logical arguments for design decisions gives a designer authority and can be valuable to include discussions of the implications of the design. It also helps developers/engineers make fully-informed decisions about how to implement the design.

Grid Locked

The design of the document itself must be visually clear and maintain consistency from page to page by relying on a fixed grid of page elements. The text must all line up and the header, footer and margins must be uniform across each page. That’s what we call the grid. The clean, organized layout allows readers to find things on the page or to make sense of the content they see apart from aesthetic reasons.

This was a primer on designing documents that showcase or highlight your product/service/design to an audience that wants to know how and why things work in the simplest manner possible. Reference guides must present information clearly and concisely for programmers and the narrative must provide an overview of each element of the design using a clear format, like bullets or numbered lists. Thus the structure of the design document depends on the needs of the audience entirely with minimum focus on aesthetics and maximum focus on functionality and usability.

You might also like


Leave a comment

Ritesh Reddy

Dr. Ritesh Reddy, PhD aka Reddy2Go is a Creative Generalist, who uses the magic of the written word and the allure of the visual medium in conjunction with bleeding edge technology to creating communication collateral for the New Media. He believes in the power of the individual & inspires independence through the Freelance Firestarter. In the spirit of selflessly sharing knowledge with the community for the betterment of society, he does not charge any fee for the same.