2019-03-18

    A better web development workflow: Confluence, Airtable, Jira and Abstract

    Working as a front-end developer for nearly two years, I've got precious experience from being part of several web development projects of design/digital agencies.

    One obvious but valuable lesson I've learned is that collaborating between each group with the same goal but distinct responsibilities and purposes are not easy. Of course, there’re different aspects and levels in terms of collaboration, and the specific part of which I’d like to address is the workflow process.

    Based on the previous experience, with the help of my designer and developer friends, I built a website development workflow designed for a small team (5 - 15 people). The system is composed of Confluence, Jira, Airtable, and Abstract. In this article, I’ll share the why and how of this workflow.

    The motivation for building a new workflow

    To deliver a customized website without using templates provided by website builders, a minimum talent requirement includes designer, developer, and project manager. After participating in a couple of cases, I had a sense that there’s something wrong about the workflow we had because important information was always not aligned both internally between different roles and externally to clients. This inefficient communication was clearly slowing down the development cycle and hurting the team.

    So I started to solve this problem.

    Google search workflow great resources: Design systems features, style guide resources and workflow definition Google search workflow great resources: Design systems features, style guide resources and workflow definition

    I Google searched resources about establishing and improving workflow. Though I learned a lot from all the great resources, I found nearly none of which was for web development projects in design/digital agency. It’s either a design system or coding guidelines that scoped in design or front-end roles, or workflow that built for the team with its own product. As a result, I decided to cherry-pick the parts I needed to solve our problems, and formed a customized workflow for website development.

    Problems and goals

    The following are the problems I inspected from our existing workflow, and the corresponding improvement goals.

    waterfall model abstract demo waterfall model abstract demo

    1. Waterfall methodology

    Problem: Based on my experience, website projects adopt a waterfall approach because clients don’t have a concept of the minimum viable products (MVP). Instead of splitting functionalities from views and modulization, clients tend to think the site in a traditional page-by-page way, which forces both designers and developers to work page by page in sequence, hence losing a universal perspective across the project. This situation results in lots of back-and-forths redundant revisions between pages.

    Goal: Changing the mindset of clients is both arrogant and unrealistic. The goal is to find a way to separate requirements from views as soon as possible and develop as modulized as possible internally based on the page-by-page model.

    design tokens from Salesforce design tokens from Salesforce

    2. Universal design tokens and components managed by both designers and developers

    Problem: This is a common issue that a lot of articles have shared great solutions, which mostly propose building a design system that managed by style guide/library generators. Though it is a great solution, managing an extra site that barely provided edit permission to designers was not appropriate in our situation.

    Goal: Except for creating universal design tokens and languages that designers, developers, and managers can all understand, build a system that allows everyone to manage the assets in a synchronous way.

    we need an editable and accessible progress dashboard we need an editable and accessible progress dashboard

    3. The accurate, updated progress dashboard

    Problem: Though issue tracker, kanban, and more project management models are useful and practical, most of them failed to act as a straight forward, flexible, and friendly progress dashboard. This kind of dashboard would save the team a lot of time because it prevents team members from actively reporting or asking the current situation of specific tasks. It also makes managers' life easier to have a clear knowledge of the entire project without too much effort.

    Goal: Build a dashboard system that provides edit permission for an individual in charge of specific tasks.

    Workflow diagram

    workflow diagram I designed workflow diagram I designed

    Before we dive into the detailed introduction of management tools stack, let’s take a look at the abstract simplified workflow I organized. It’s pretty much just a visualization of a normal workflow that most agencies have, but there are two points to be noted here.

    1. Developer evaluation

    First, when a requirement or issue coming from the client is approved and documented by the manager, except for sending the task to the designer, it also goes to the developer for evaluation. In this process, the developer reviews the specification of the task, making sure if there are any rather complicated functions or features included. If it’s positive, the developer could start working on it or notify the designer of the potential problems beforehand.

    2. Single source of truth

    Also notice that after design deliverable is approved by the client, before handing the task over to the developer’s hand, it goes through a process of register/modify/delete over design store conducted by the designer. This is because the developer should always be exposed to one and only source of design store, which contains constantly maintained and updated assets ready for development.

    Now we can dive into the management tools stack I prepared, and see how the tools help us solve the problems.

    The tools stack

    After experimenting with various options on the market, the stack I’m proposing here is composed of Confluence, Jira, Airtable, and Abstract. In addition to the basic introduction and a few key application examples, I’ll not cover all the details of using the tools.

    Note: the system assumes that the development team adopts atomic design methodology and ABEM naming system.

    1. Confluence

    Role: information and resource center

    Though it’s intimidating at first, Confluence provides a powerful workspace that’s easy to organize, and have tons of features, integration of apps, and customized templates. It’s definitely not a universal solution to all problems, but it’s perfect for documentation of specifications, requirements, meeting notes, and more. Therefore, Confluence in this stack works as an information and resource center, which means every related links and detail about this project should be documented properly in here.

    My favorite advantage of Confluence is the ability to customize document templates. This feature provides great convenience at standardizing the workflow.

    developer evaluation stage developer evaluation stage

    Example: Component functionality review

    We mentioned the developer evaluation process above, which is actually a complicated job. Because this process includes basic information of the component, developer’s FSM review (if necessary), FAQ space, and more. But the flexibility of the template and tools Confluence provides makes this super easy. Just build a template in configuration settings and you’re good to go.

    custom template for component review in Confluence custom template for component review in Confluence

    2. Jira

    Role: issue tracking and action type management

    Also, a member of the Atlassian family, Jira is a super powerful issue tracking and project planning software, and my favorite part of which is making customized issue workflow. Since there are tons of great tutorials on how to utilize the power of Jira, the only thing I want to point out here is using issue type as mentioned below.

    designer update design store designer update design store

    Example: Update developer on changes of design store by issue type

    To ensure that developers are building the components based on correct design views, they need to be notified whenever something in the design store is being updated, which includes the action of register, modify, and delete. So, as the component is updated, the designer should open an issue with the responsible developer assigned and the correct issue/action type selected.

    3. Airtable

    Role: component management and a progress dashboard

    Airtable, a mixture of spreadsheets and databases, is the one that makes this stack works. There are two amazing features that support my workflow: four types of view transition in a single table and related content linking. I’ll showcase two examples of using these two features here.

    developer starts working on the task developer starts working on the task

    Example 1: Component management

    How to manage the component library? We chose not to use a style guide generator because it’s not accessible for designers to edit. Using Sketch component library wasn’t appropriate either, because it’s got too many limitations if we tried to use it outside the scope of the software itself.

    I wouldn’t say Airtable is a perfect solution, but it’s the easiest and most flexible option I could think of. Take a look at the demo template of component management table here:

    component table component table

    Once a newly registered design view that’s ready to be developed programmatically is submitted to the developer, he/she would asses the view based on the ABEM system, and registers it into the table. There are 9 columns in the table, including:

    1. Name - the naming of the component in ABEM principle
    2. Preview - screenshot or exported image of the component
    3. Linked page - link to the page contains this component
    4. Children component - link to children components this one contains
    5. Modifier - checked if there are style variations (ex: —active, —red)
    6. Component category - a general category classification (ex: text, hero, sidebar)
    7. Development status - the status of development progress (pending, assigned, in progress, complete, in revision)
    8. Assignee - developer responsible for this component
    9. Atomic level - the atomic category of this component (atom, molecule, organism)

    The best thing here is that you can refer to data in both the same and other tables. This connection of dots prevents things from getting messier as the scale grows. Also notice that you can filter, sort, and change views easily.

    Example 2: Page development status

    Since the assumption here is that we’ll inevitably asses development progress page by page, a table template designed for this purpose is necessary. This table can be a progress dashboard for both the internal team and shared with the client at the same time.

    page list table page list table

    Any information about the page, including deadline, InVision prototype link, assignee, and children component, can be organized here. Note that it’s very convenient to document and update design, front-end, and back-end development status at the same time.

    4. Abstract

    Role: single source of truth and design assets version control

    Abstract is GitHub for Sketch assets that save designers from the hell of copying and pasting of files. It’s out of this article’s scope to demonstrate the details of managing version control flow. The key takeaway here is that the Abstract is the design store that acts as a single source of truth. Designers should keep updating the master branch to the latest version of the confirmed design and notify developers. On the other hand, developers should only take design assets in the master branch as a reference.

    More works to be done

    From my own experience, the development speed of the entire project after adopting this new workflow is at least two times faster than before. It's not a perfect solution, because it still requires lots of manual labors to update and maintain. But I think it could be a helpful reference to website development teams searching for better workflow, and hopefully, more people could share their workflow in the future!