Atlassian Documentation for Product Design Teams Part 4

Jiri Mocicka
7 min readMay 3, 2021

“Design is a conscious and intuitive effort to impose meaningful order. Design is both the underlying matrix of order and the tool that creates it.”

— Victor Papanek

In the last article, we look at the structure that increases transparency across the business. This article aims to answer all the questions related to design sections, namely Content, Customer Experience and User Interface Design.

4.0 — DaS Content

Figure 02: The Content is the king

Content is the king, and every experience succeeds or fails depending on the quality of the copy. In a complex organisation, this section can become indispensable for people of words–copywriters.

During one of my collaborations with a copywriter (or Storytelling department and LBG), I saw the need to establish a comprehensive approval system. It was quite a complex task with lots of emails. A unified approach in Confluence where all stakeholders can see what the previous one has or has not agreed with is best–legal, risk, operation, management etc. By defining clear business rules and processes, 20+ stakeholders could conclude 6-times faster than they could via emails. This section unifies the copyright issues inside a business group and helps a brand define the language and editorial guidelines that significantly improve all digital properties.

All communication channels are organised in this area. The key collaborator was Alex Keller; he single-handedly implemented this framework in the Lloyds Banking Group Storytelling department and gained significant recognition amongst his fellow writers.

The learning here is that sharing knowledge gains more recognition in wider groups than who takes the credit over final implantation.

5.0 — DaS Experience

Figure 03: The Navigational Model

Inevitably, this session describes experience principles, navigation and behaviour model and contains the list of features, patterns, and templates in the proposition.

If you find yourself working with Figma, you’ll discover that documentation is as easy as free-flow. Figma allows you to hold all the latest information in CX+ UI design where your written word remains on Confluence.

For more than a decade, I have defined all features on a separate page. The reason behind that is that features come and go (as the priority or the budget). This structure allowed me and my colleagues to evolve quickly without losing the work and neither changing the tools. Confluence also allowed me to see the history and my first draft of the page, including the latest update I made an hour ago.

These feature pages that start with “FAT” (about naming convention perhaps later) are linked to JIRA user stories. This simple workaround saves time writing the user stories in different places and maintaining different versions of them.

Equally, the components and patterns can be described in simple text (I use the /code macro), allowing me to discuss all changes and implications quickly. Figma has inevitably made a massive impact on how design-related work is communicated and delivered across the team. Figma Macro makes all our work visible to all our developers and business owners. This creates absolute transparency throughout an entire project.

The learning––Designers tend to start designing unique maps, wireframes proposition in colours. The most valuable insight here is that most decisions can be defined in simple text and then translated onto visual experience maps, navigational modes, etc. In this case, we saved roughly 10% of the time on re-design the non-essential materials for the delivery and gained more time designing the UI.

6.0 — DaS Design

Figure 04: The Product Design Development Flow

The design section has been a controversial one. The main question here is, “where does the design live?”. Simply put, the designers do not like documenting, and therefore anything around documentation was quite a challenge. Historically we have had PSD’s, AI’s, FireWorks even InDesign files later Sketch and Figma. Outside of Figma, all the design apps carried out the challenges with versioning, export of the assets and measurements, just to name a few.

For those interested in running the documentation with these dinosaurs of the design industry, drop me the DM to discuss it separately.

Assuming that you have Adobe Xd Cloud, Sketch Cloud or Figma, you can link your design to a Confluence page.

The Design section combines the Design Principles, Design System, Mission Statement, Manifesto, Component Library, Pattern Library and lately even Figma sub-section.

Design Principles–inherently focus on principles defining the experience and overall guidance for the product. Where the Design System focuses on colour, typography, templates and other building elements. Mission Statement and Manifesto unifies the beliefs of the team and what the company stands for. Interestingly enough, some proposition does not see it as vital. When asking different team members what the product stands for, I usually get ten different answers–go figure.

With the arrival of Figma and the capability to share individual pages/views, it is relatively easy to document an entire pattern library in a few weeks.

Component and Pattern Library–has become indisputable for most remote teams, and the Figma has strengthened this capability even more.

The example: I was helping a young fashion startup deal with product integration across their digital properties. First, they defined the guideline and design system in a simple (RTF) text file to great detail, then created a set of empty pages that they can shift around. This helps them to unify their thoughts first and then choose the right tool to do the work. Even changing the design tool from Sketch to Figma had no impact on their delivery timeline. This simple example proves that software transition has no impact on the delivery.

The second example is from the financial transformation, where five teams were delivering one single proposition. Five teams, five designers are combining fifteen different sketch files unifying three (constantly evolving) brands. Not even mention that each team has a different paste and different delivery date. After over a month of analysis and unifying everything in one place, it took one two-hour (2) meeting to speed up the process and deliver all five products two months earlier.

All of this sounds quite fun. There is the other side of the story. Some of the work has been completely wasted, never seen or even integrated. The latest version of Confluence had no integration for Sketch, inVision or Framer. Only now we see these things popping up.

Equally, delivering assets through Confluence or JIRA is most definitely NO.

I have tried with several teams, and it all falls on one premise: no one wants to update the page with new assets when updates happen constantly.

On the bright side of things, quite recently, the latest integration with Figma has been quite a delightful experience. The last two startups and one SME platform delivery have comprehensive Confluence Documentation in a Design System including Brand Bible, Templates and components. On this topic, perhaps sometime later.

Common Questions

Information maintenance

Figure 05: The Information maintenance vs information clutter.

Generally, all can easily fail because of information maintenance. People are generally quite lazy, and doing extra work to save someone else’s time seems less valid than keeping your own time. A little sacrifice has a tremendous impact on the company’s productivity.

Studies show that 16% of the time is wasted in ineffective communication — this makes it one day from a week lost. Out of the 14-years of implementing DaS™, only eight (8) teams truly added value and become scaling design and development together. Rightly gained a significant advantage amongst the other teams by investing energy in things that matter to the team and not themselves.

Versions and Sign-Off

Figure 06: The 80/20 communication rule

Confluence holds version control embedded in documentation which comes as a significant benefit to the team. To enhance the importance of the page (hub), I have developed a “Header” that has been consistent across main hub pages to communicate the following:

  • Owner
  • Sign off date
  • Release
  • Delivery
  • QA

Such an element created a standardised way of what the user gets on every page. It also creates the rhythm of pages and subpages (Macro: Child Page) alongside TOC (Marco: Tabel of Content). Once the pages reviewed and agreed, mainly in the meeting, I (or the CPO) has locked it down and assign it for the next sprint.

Collaboration and Ownership.

Figure 07: The remote collaboration in numbers.

Page ownership is debatable, yet it comes to a section and the department responsibility that designers maintain design and developers maintain development pages. It’s everyone responsibility to drive the definitions and the quality as higher as possible. The structure needs to be constantly reviewed to prevent the duplication of pages. It truly is a delightful experience if you see the entire team contributing to one definition.

Whether the designer contributing the testing or the business analyst contributes to the design; shows the ultimate team’s maturity.

Stay tuned; thanks for reading!
Thanks to all contributors especially
Matt Press, for their insight and comments shaping this very article.
Jiri Mocicka is a London-based designer writing about his passion for the
Design at Scale — integration and design operations that builds excellent digital products.