Start small, aim big: Designing an approach to creating technical diagrams

by Will Burroughs (IBM) and Ya Qing Chen (IBM, IE)

Pictures tell a thousand words, and for complex software, a good technical diagram helps readers understand a product. But how to create compelling diagrams in a consistent way for large and complex products? That was the challenge I undertook as a visual designer working at IBM. This is a story where I set out to help content designers improve diagrams in the technical content, but ended up in a Figma library benefiting 94 teams in IBM and the wider open source community, using design thinking techniques.

The challenge

A key component of product content is accompanying technical diagrams. They break down a complex architecture in straightforward visuals, to aid users’ understanding.

In early 2021, our content team for a complex software product called CICS that runs on the mainframe found themselves struggling to create technical diagrams: The tools were complex, the process time-consuming, and the workload just huge.

As a result, I, along with another content designer from CICS, brought together a small group consisting of Content, UX and Visual designers from across CICS to resolve the problem.

A hill to work towards

Our team used IBM’s Enterprise Design Thinking everyday to solve customers’ problems so it was a no-brainer for us to tackle this challenge using this technique.

When we mapped out the as-is experience of the content team, we saw they were confused and had many unanswered questions that affected all aspects of diagram creation.

The mapped out as-is experience.

The most pressing pain points discovered from the activity were:

1. Inconsistent style in diagrams due to lack of official IBM guidance for technical diagrams. The CICS design team created an internal visual guide circa 2015. However, the guide lacked detail for practical usage and went out of sync with how IBM’s design philosophy and principles, the IBM Design Language (IDL), evolved over time.
2. High learning cost of the graphic tool and low efficiency in diagram creation. The content team had migrated to Adobe Illustrator for a while. While it was an incredible tool for visual designers to produce illustrations, content designers found it hard to grasp due to their scarce formal background in graphic or visual design. Adobe Illustrator’s powerful functions tended to be an overkill for the structured tech diagrams.

To better understand the as-is scenario, we conducted an audit to review diagrams across the CICS documentation (CICS has been in service for over 50 years! so that’s a lot of documentation). We categorized the diagrams and identified common themes and concepts, to prioritise diagram types and elements to work on.

An example of the type of diagram the team were creating included in the audit.

Finally, we defined our hill to keep us focused on what we would deliver as a solution. We were now ready to take the hill and start designing!

An MVP

At IBM we are fortunate to have a global family of 1800+ designers spanning all disciplines — UX, animation, industrial, graphic, research, UI, content. This means when you start something, you may well find someone else already working on something similar to collaborate with. If not, there may well be folks willing to help if asked.

Unsurprisingly, we found the brand experience and design team already working on a design framework for IT Architecture diagrams. Although that work was still in progress, I could develop guidance for the CICS content team in parallel based on their framework.

IDL’s architecture framework.

With what we discovered from our own audit, we applied meaning to components from that in-progress design framework to cater for CICS’s use case. We eventually delivered in Adobe Illustrator a visual guide, a starter kit and a set of re-worked UI icons specific to CICS which aligned to IBM’s current design language, enabling the team to use the complete IBM UI icon library moving forward.

The final diagram guidance.

This filled the gap of a missing framework for technical diagrams. However, just as big a part of the puzzle was what would be the best tool to create diagrams in?

A missing piece to the jigsaw

The tool problem became more evident as the content team started to use the guidance and assets. Although we made a stride forward, Adobe Illustrator left too much in the hands of the creator and could lead to human errors.

As a visual designer, I’m familiar with component-based design. I figured a tool that supported reusable components would remove design barriers for content designers and ensure the integrity of our design system.

As IBM Design announced Figma as one of the strategic design tools, we explored Figma and quickly came to the conclusion that this could be the missing piece to the jigsaw. With its stripped back UI, the ability to create components, collaborate, comment and being web based allowing our team access irrelevant of their preference of using macOS or Windows. Had we found the silver bullet?

Nothing ventured, nothing gained

We reached out to the brand experience and design team to find out if they planned to create a diagram library in Figma similar to the Carbon libraries (Carbon is IBM’s open source design system for products and digital experiences), in addition to the existing .ai starter kit they provided. The answer was “No, but that’s a great idea. You should create it!” That’s why it’s such a special place to work. There’s opportunity everywhere if you want it.

We were all new to Figma and none of the team had experience of creating a library. Therefore, we not only spent the next month in and around our day job responsibilities putting together a prototype, but also connected with a guild focused on Figma (Within IBM, we use guilds to drive us forward delivering specific outcomes). They agreed to mentor us and met with us biweekly to review and improve the prototype components, ensuring they were up to the standard of Carbon libraries.

We also shared the prototype library with several teams and gathered their feedback for any bugs and potential use cases.

Within a few months we had a working library.

The library in action in Figma.

Outcomes

The library was initially released to the IBM community as a beta in October, 2022 as an addition to the IDL technical diagram framework. We have then delivered regular updates through continuous delivery ever since.

“ This library makes a big difference to our content team and, by extension, to product users. The content team can create consistent, high-quality diagrams and focus on conveying the right information for the user instead of wrestling with tools. Client feedback shows that diagrams are valued — and this library means that we can respond with more (and better) diagrams in our documentation.”– Content Strategist, IBM CICS

“ I would estimate that having this Figma framework and library has
accelerated our technical diagram creation and update process by roughly
5–6 times easily, likely even more in case of really complex topologies.
Designer, IBM Cloud

Up to now, the library has been used by 94 teams within IBM, and has an average of 4.8k inserts per week.

A Figma community version, was also released earlier this year to benefit the broader community.

1. The collaborative nature of Figma enables content teams to input and improve assets with design easily, which leads to improved quality of our technical diagrams.
2. More importantly, the modular design empowered by Figma components improves the productivity and ease of diagram creation.
3. Maintenance wise, it’s easier to make changes on the fly and scale them out to the team and beyond.

Takeaways

We set off this journey to solve a specific problem of our team. Yet we ended up delivering a library that is now helping 94 teams across IBM and even more in the Figma community.

Looking back I’d like to share some takeaways:

1. Think big. Although you might start with tackling a problem of your own team, it’s always useful to think about the big picture. Could this benefit a bigger audience? What about maintenance in the longer term, by other contributors? Such questions are important to your solution’s sustainability and impact.
2. Be part of your community. During our journey we received help from the design community at IBM and in turn gave back with a Figma library. It’s this spirit of collaboration and giving back that enables everyone in IBM to team up, and to exert influence in a larger, open-source community.
3. Think for your users. In our story the content designers are our main target audience. Therefore, everything we’ve done, including the design thinking hill, choice of the graphic tool, revolves around them. This ensures we have a focus and stay aligned with a clear goal.
4. Give your beta enough time to collect feedback and identify bugs. We ran the library as a beta for three months. With hindsight a little longer would have been better.

Wanna try it out?

IBM’s Figma technical diagram library is available as a community version here. Be sure to check out the technical diagram guidance at IBM Design Language.

A community version is available at Figma.

Thank yous

Thanks go to those who made all this possible:

1. Ya Qing Chen, content designer from IBM CICS. She co-led the technical diagram project of CICS and created the Figma library with me.
2. Diana Stanciulescu, creative director, design principal from IBM Blue Studio. She designed the IDL diagram framework that laid a foundation of the Figma library. She also offered support and guidance to ensure the assets created by us were IDL compliant.
3. Juan Encalada and Pat M Clough, design lead and senior designer from IBM’s guild for Figma. They provided support to ensure our library and the accompanying guide were up to IBM’s Carbon standards, and helped with the publishing and maintenance of the library.
4. Sponsor users who adopted the library early and provided feedback, especially Silvio Hajdin from the IBM Cloud Satellite team who actively participated in our discussion and contributed examples.

Will Burroughs is a Visual Designer at IBM based in Hursley. The above article is personal and does not necessarily represent IBM’s positions, strategies or opinions.