Getting Started

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.

Creating a Spec Issue with Jira

Create a new issue with a descriptive title, e.g.

“Property Index”
“Add business hours to the Space Detail”

Avoid long phrases with extraneous words. The title should simply reference the component, action or view.

Writing the Spec

All spec details should live in the issue description, including images and other attachments. Below are details we generally include:‍

User Story

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

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”

Interactions

“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”

Animations

“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”

Data

“Content comes from the Project Name API”

Exclusions

“The ability to collapse cards should not be implemented until the next release”

Mockups

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)
Save Menu
List View (Edit Mode)
List View (Saved)
Confirmation Toast
Error Toast

Demos

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.

Assets

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.

Approval

Every spec issue needs to be approved by the client before development can begin. This approval needs to be documented on the issue.

Have a Call

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.

Follow Up

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!

Success

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.

‍

Written by

Brian Smith

As the Vice President of Design at FullStack Labs, I lead a team that specializes in user experience and interface design, through rapid high-fidelity prototyping, user flow creation, and feature planning. I have over a decade of experience designing complex software applications with a focus on user-centered design principles. Prior to FullStack Labs I was the Creative Director at Bamboo Creative and the Director of Design at Palmer Capital. I hold a B.A. in Design from UCLA.