Advanced design tools like Figma, Invision, and Sketch allow designers to build clickable, high-fidelity prototypes that demonstrate many of a product’s expected behaviors. Certain behaviors, however, cannot easily be demonstrated with these tools and require additional documentation for successful implementation. It is difficult to communicate complex animations or, for example, the desired response when a server is loading slowly. Quality documentation allows designers to provide developers with the information that modern design tools struggle to convey.
Collaborative, live documentation keeps everyone on the same page throughout the development cycle. Passing around PDFs every time a change needs to be made is cumbersome and can lead to miscommunication. (Note: Although live documentation provides a single source of truth, developers will need to be notified of any changes made after development has begun.)
We generally document design specs in Jira, but have successfully leveraged Google Docs and Confluence in the past. Below is our process for creating the documentation in Jira.
Create a new issue with a descriptive title, e.g.
Avoid long phrases with extraneous words. The title should simply reference the component, action or view.
All spec details should live in the issue description, including images and other attachments. Below are details we generally include:
User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. They typically follow a simple template:
Acceptance criteria are notes on the conditions a feature needs to meet to be considered complete. This criteria can vary in complexity depending on the project, but often includes information on UI, interactions, animations, data, and exclusions.
Mockups are critical to convey the intended implementation to developers and clients. Include a link to all related views in the description. If the spec issue references six views, for example, the description should include six links.
If a workflow is particularly complex, record a demo using a screen recorder and incorporate the video into the issue. In the future, this can be referenced by any developer who joins the team.
Providing the correct assets to the development team is critical to achieving the expected implementation. Include links to where the assets should be pulled from or attach them directly to the issue.
If your design leverages any existing code repositories, such as Material Bread, include a link so the development team doesn’t waste time rebuilding functionality that already exists.
Every spec issue needs to be approved by the client before development can begin. This approval needs to be documented on the issue.
After the client has approved your completed spec issue, set up a call with the development team to review it. Update the issue with any changes that are required as a result of the call. If possible, record the call and include a link in the description.
Check in regularly with the development team to answer additional questions or clear up confusion. There is a 100% chance you missed something in your specs or didn’t explain something clearly enough. That’s OK!
Building software is complicated. Creating thorough documentation will help ensure you won’t be pulling your hair out in six months when the app you so thoughtfully designed goes into beta testing and doesn’t match your expectations. The success of the team as a whole hinges on proper design documentation.
At FullStack Labs, we are consistently asked for ways to speed up time-to-market and improve project maintainability. We pride ourselves on our ability to push the capabilities of these cutting-edge libraries. Interested in learning more about speeding up development time on your next form project, or improving an existing codebase with forms? Contact us.
We’d love to learn more about your project.
Engagements start at $50,000.