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.
“Add business hours to the Space Detail”
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:
“As a [type of user] I want [some goal] so that [some reason].”
“As an Administrator I want to be able to create User Accounts so that I can grant users access to the system.”
“As an app user I want to be able to submit polls with premium features and be charged for them through Apple Pay and Google Pay so that I can poll the community.”
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.
“The UI matches the mockup (see link)”
“First time users will see an empty state illustration and text”
“Clicking edit transforms the view to an edit view”
“When clicking Save the user sees a toast notification”
“If the user clicks Cancel the view reverts back to read only with no toast notification”
“Navigation is disabled for logged out users”
“The page loads from top down”
“A skeleton loader should be used on the cards”
“When saving, show a spinner on the save button”
“If the page takes 2000ms+ to load, show an indeterminate linear loader”
“Content comes from the Project Name API”
“The ability to collapse cards should not be implemented until the next release”
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.
List View (Read Only)
List View (Edit Mode)
List View (Saved)
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.
Relevant Hyperlinks to Code Repositories
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. Contact us below for a free consultation with our CEO.
Projects Start at $25,000.
An interpreted high-level programming language great for general purpose programming.
A server side programming language known for its ease of use and speed of development.
View a sampling of our work implemented using a variety of our favorite technologies.
View projects implemented using this high-level programming language great for general purpose programming.
View projects implemented using this framework that allows rapid development of native Android and IOS apps.
View projects implemented using this server side programming language known for its ease of use and speed of development.
Learn more about our current job openings and benefits of working at FSL.
Detailed reviews and feedback from past and current clients.
Detailed profiles for each member of our team.
Our step-by-step process for designing and developing new applications.
Get answers to the questions most frequently asked by new clients.
Learn more about FullStack Lab’s Mission, Vision, & Company Values.
A high level overview of FullStack Labs, who we are, and what we do.