2019-03-18

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

    Working as 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 learnt is that collaborating between each groups with a same goal but distinct responsibilities and purposes is 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 workflow process.

    Based on the precious experience, with the help from my designer and developer friends, I built a website development workflow designed for 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 the this workflow.

    Motivation for building a new workflow

    To deliver a customized website without using templates provided by website builders, a minimum talents 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 client. 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 a 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 design system or coding guidelines that scoped in design or front-end roles, or workflow that built for team with its own product. As a result, I decided to cherry picked the parts I needed to solve our problems, and formed a customized workflow for website development.

    Problems and goals

    Following is 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 waterfall approach because clients don’t have concept of minimum viable product (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-forth redundant revisions between pages.

    Goal: Changing 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 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 great solution, but 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. 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 current situation of specific tasks. It also makes managers life easier to have a clear knowledge of entire project without too much effort.

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

    Workflow diagram

    workflow diagram I designed workflow diagram I designed

    Before we dive into the detail 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 agency have, but there’s two points to be noted here.

    1. Developer evaluation

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

    2. Single source of truth

    Also notice that after design deliverable is approved by client, before handing the task over to developer’s hand, it goes through a process of register/modify/delete over design store conducted by designer. This is because 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 basic introduction and few key application examples, I’ll not cover all the details of using the tools.

    Note: the system assume that development team adopt 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 details 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 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 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’s tons of great tutorials on how to utilize 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 design store is being updated, which includes action of register, modify and delete. So, as component is updated, designer should open an issue with responsible developer assigned and correct issue/action type selected.

    3. Airtable

    Role: component management and progress dashboard

    Airtable, mixture of spreadsheet and database, is the one that makes this stack works. There's two amazing features that support my workflow: four types of view transition in 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 component library? We chose not to use 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 much 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 developer, he/she would asses the view based on ABEM system, and registers it into the table. There’s 9 columns in the table, including:

    1. Name - naming of the component in ABEM principle
    2. Preview - screenshot or exported image of 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’s style variations (ex: —active, —red)
    6. Component category - a general category classification (ex: text, hero, sidebar)
    7. Development status - status of development progress (pending, assigned, in progress, complete, in revision)
    8. Assignee - developer responsible for this component
    9. Atomic level - atomic category of this component (atom, molecule, organism)

    Best thing here is that you can reference to data in both 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 internal team and shared with 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 saves designers from hell of copying and pasting of files. It’s out of this article’s scope to demonstrate details of managing version control flow. The key takeaway here is that Abstract is the design store that acts as single source of truth. Designers should keep updating master branch to latest version of confirmed design and notify developers. On the other hand, developers should only take design assets in master branch as reference.

    More works to be done

    From my own experience, the development speed of 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 helpful reference to website development teams searching for better workflow, and hopefully more people could share their workflow in future!