A designer’s guide to project documentation

4 minute read
Feature

Taking a product from a mere idea to a launch is not a one-person job. It’s not even a one-team job. What ultimately goes out into the world is shaped by multiple teams — business, design and engineering. This means that information and context needs to flow from one team to another and one person to another, seamlessly.

And that is easier said than done.

Design isn’t just about the final UI. Designers conduct user interviews, synthesise research documents, take product decisions and create component libraries or design systems for a uniform user experience. When documenting a project, all the work, thought processes and decisions that led to the final UI need to be a part of that.

In a remote work environment, documentation assumes even more importance. One can no longer walk over to someone’s desk and ask them why they designed something a certain way or where to find a particular file.

Documenting a project well starts with having the right mindset: Start the project with an understanding that it’s going to end at some time. Thinking about documentation from Day 1, rather than in the final week can make all the difference. And here’s how you can do it:

The Obvious checklist for project documentation

Create shared drives

When the project starts, if there is no shared repository between teams, create one. Put all assets like fonts, template images, Figma files, presentations, PRDs and DRDs here. If you’re using project management softwares like Jira and Confluence, create shared drives there.

Asset 14


Increase design-engineering knowledge transfer

Engineers usually tend to get involved very late in the design process and that creates multiple issues around certain designs not working, some elements breaking and so on.

  • To ensure easy transfer between designers and engineers, they need to start communicating as early as possible, right when the designers start pushing pixels.
  • Once basic concepts or wireframes are ready, it’s healthy to seek insights from the developers on how design elements would translate to code. It’s useful for designers to know about engineering constraints before they start designing the final UI so as to not waste time redoing it later.

Follow the The Hot Potato Process

The exchange of ideas between designers and developers should be happening for the entire product creation cycle. This inculcates a good shared knowledge which can be carried forward easily and can work wonders even for distributed teams.

Asset 15

Create prototypes and share links

A working prototype goes a long way in conveying information about different flows and decisions. Attach links to these prototypes alongside final flows and ensure an easy way to leave comments/feedback.

Add annotations for animations

Before you give a walk-through of your designs to engineers, make sure you write down small annotations next to your flows and screens which will help engineering understand it easily even later in the process and reduce scope of breakdowns in communication. For example: Transition(FadeIn, 0.5seconds,L→R)

Maintain a decision record

Minimise the knowledge gaps between designers, developers, product managers by keeping track of every product decision you take while designing. It can either be done on Figma with annotation, or you can maintain a separate file for this on any shared apps like Linear (great for raising tickets and resolving) or Asana (great for managing tasks). These design tickets really help in ensuring there is less to and fro between the same discussions.

  • Take the time to document, and more importantly, discuss the rationale for design decisions. This will pay dividends in an end-product that serves users, not just ticks the boxes of specs.
  • Attach links to your decision records, design tickets to every design that is taken to production. It becomes helpful because individuals are able to refer the explorations you went through and the decisions you took to change them.
Handover3

Design checklist before the handover

Before you prepare for the handover to engineering, check your design for the following things:

Quality

  • Are you proud of your design?
  • Design adheres to set design principles

    Insight

    • Design helps users achieve their goals
    • Design caters to all scenarios and cases
    • Tested the design with real users

    Content

    • Design meets the accessibility guidelines
    • Discussed all the data featured in design
    • Covered potential cases & states like, corner cases, edge cases, empty states, error states
    • Copy follows the writing guidelines and checked
    • Assets like, icons and images are made exportable & updated in style guide
    • Components have been updated in style guide with their variations
      • Possible states and variations
      • Constraints and responsiveness
      • Sub-components state & variations. for eg, empty, filled, error states
      • Interaction states
    • Required interactions/animations details are marked & mentioned
    • Making a walkthrough of the whole hand off can be super helpful
    • Delete all unused guides, components


    Final week

    In the final week of your project, all the documentation needs to come together. Try to clear out the week to organise and check your documents. This is important because different teams and stakeholders will continue working on the project and will need access to your work.

    • Put together an index and order your work chronologically and feature wise. For example, User interviews ➡️ Insights ➡️ Designs.
    • Organise knowledge sharing sessions between all stakeholders.
    • Keep time aside to answer questions or address concerns as quickly as possible.

    The final word

    Good project documentation is crucial to creating a great product. It can feel like documenting everything is slowing you down and coming in the way of doing the actual work. But in the longer run, it minimizes conversations with stakeholders about product decisions and saves time. Let documentation not be an afterthought, but a plan from day zero.