Should you document your design system in Confluence?
Jules Mahe
In previous articles, we delved into popular solutions like Figma, Storybook, and Notion, exploring their effectiveness in documenting design systems. Now we shift our focus to Confluence, a widely used collaboration platform known for its versatility in housing various forms of documentation. We’ll weigh the pros and cons and assess its capabilities in facilitating design system documentation.
You may be wondering:
- Is Confluence powerful enough for your design system?
- Is it the right solution when you scale?
- Are there any limitations and blockers you might encounter?
Let’s explore the possibilities of using Confluence as your design system documentation.
Benefits of using Atlassian’s ecosystem
A centralized solution for everyone
One of the standout perks of using Confluence for design system documentation lies in its integration with Atlassian’s extensive ecosystem. By leveraging Confluence’s seamless connection with tools like Jira, teams can experience a harmonious collaboration between design system documentation and project management processes. Linking design system documentation to specific Jira issues or development tasks ensures that the documentation remains contextually relevant and readily accessible throughout the entire development lifecycle. This integration facilitates a smooth flow of information between design and implementation, enabling teams to stay aligned and efficiently tackle project challenges.
Confluence’s compatibility with other Atlassian products, such as Bitbucket for version control and Trello for task management, creates a cohesive ecosystem where design, development, and project management activities effortlessly converge. The comprehensive integration within Atlassian’s ecosystem empowers teams to streamline workflows, enhance communication, and drive the success of their design systems with unparalleled efficiency and effectiveness. Bringing everyone into the same tooling ecosystem may seem like a good idea. It allows teams to have one source of truth, but it’s actually not that straightforward. General documentation, like meeting notes, team processes, and product wikis, is a breeze with Confluence, but more is needed when documenting a design system. Because Confluence wasn’t specifically designed for design system documentation. This is apparent when integrating design and tech tools is not smooth and powerful enough for the design system team’s needs. As a result, most teams who use Confluence to document their design system experience a siloed and scattered process where all the code and specs are kept separate. Consequently, teams don’t have one-stop access to their design system documentation. Beyond access, keeping all the documentation in sync with the code and specs isn’t a trivial task for the design system team.
Mutualized costs
Suppose a company already has Confluence as part of its existing collaboration and documentation infrastructure. In that case, the cost of using Confluence for a design system documentation platform may not involve additional expenses related to acquiring a new tool.
While there may not be an extra financial cost at first sight, you still need to consider having resource allocation for setting up and maintaining the documentation.
The platform’s general-purpose nature might lack specific design system features, potentially impacting usability and organization. Confluence’s visual capabilities are not robust for representing design elements effectively, and integration with design and dev tools might require manual hacks and workarounds. Additionally, scalability, maintenance, and performance could become concerns as the documentation grows. Teams must weigh these factors and assess whether Confluence aligns with their design system documentation needs or if a specialized tool (like zeroheight 😉) would provide a more tailored solution.
When Confluence is too much
A collaborative solution
A comprehensive design system involves seamless collaboration among various teams, such as designers, developers, product managers, etc. The collaborative features offered by Confluence facilitate teamwork and discussion within the context of documentation, helping to resolve issues rapidly and receive quick feedback. As a result of inline and page comments, @-mentions for task assignments, and simultaneous editing, Confluence streamlines communication and makes collaboration easier. If your company allows third-party extensions or plug-ins, you can also benefit from Atlassian Marketplace’s add-ons to improve the collaborative process. For instance, plugins such as Comala, help to enforce your governance and manage your organization’s content lifecycle. Although Confluence has a great add-ons and plugin ecosystem, relying heavily on external dependencies can be risky as you rely on their updates and evolutions for your documentation. For example, a single developer could create a plugin but later becomes uninterested in maintaining it.
However, it is important to know that contractors and agencies might have access restrictions when you need to share your design system with them. You may find that external contributors cannot access your design system documentation if Confluence is secured through logins/SSOs/VPN accesses.
As a result, you can’t extend Confluence’s benefits for collaboration beyond your internal team, which can be a bummer if you’re trying to scale your design system.
A powerful but complex solution
While Confluence’s ecosystem apps offer a wealth of benefits, this richness can pose potential challenges, particularly in maintaining the simplicity and ease of use crucial for an effective design system. Even though the multifaceted nature of Confluence might be empowering, it can also inadvertently hinder full adoption. The abundance of features can overwhelm teams primarily dedicated to streamlined design system documentation. This intricacy, well-suited for broader organizational tasks, might not align with the focused requirements of a design system. Complex navigation and harnessing the platform’s extensive functionalities might divert valuable time and resources from the core task of design system development. Furthermore, Confluence’s versatility, while a strength in many contexts, falls short of providing design system-specific needs necessary to integrate design and tech elements effectively. This highlights, even more, the need for specialized solutions tailored explicitly to the unique demands of design systems, as we do at zeroheight 😉, thus ensuring comprehensive and consistent documentation within your design system.
A versatile but inflexible solution
Confluence is a reliable platform for documentation, but it lacks flexibility, especially when it comes to customization. While it offers the main documentation features, it does not fully cater to design teams’ diverse needs and preferences when seeking a branded or tailored look for their design system documentation. Customizing the appearance and layout of documentation within Confluence can be limited and requires some advanced coding skills, even if some apps like Scroll Viewport can help you get more customization. In any case, it might leave teams craving more flexibility and simplicity in expressing their brand identity throughout their design system platform. As a result, design system teams may find themselves constrained by predefined templates, layout access difficulties, and styling options, inhibiting their ability to deliver a documentation environment that fits their brand and needs. This inflexibility can hinder the efficiency and consistency of design system documentation, compelling teams to explore alternative solutions that better accommodate their specific requirements.
Integrations
Integrations play a pivotal role in impactful design system documentation. It needs to sync smoothly and efficiently with the designer and developer tools mainly, but also other solutions for everyone using your design system.
Confluence offers different ways to connect your documentation to these tools. However, it often requires the use of third-party integrations to maximize its potential for design system documentation. Depending on your organization that can be an issue and severely limit your use of for Confluence to serve as your design system’s documentation.
Design integrations
Design system documentation requires good integration with designers’ tools to be impactful. Figma offers a Live Embed feature to display design elements directly into Confluence documentation pages. However, it can only displays pages from the Figma files, so it’s primarily helpful for prototypes and design files. It cannot show specific components. There is also no way to automate uploading colors and hex values, elements, icons, etc., from Figma libraries, which can lead to a ton of repetitive and detailed work to create. It is also worth noting that the integration is not seamless for everyone, as the Figma embedding plugin for Confluence occasionally shows a login prompt or does not render anything for users without Figma access. Of course, you could use images instead, but it would add complexity for the upkeep, as it can be easy to lose track of updates and fall out of sync with Figma files. Consider all the different steps it involves: create the specific images for each element, name them, export them, annotate them, upload them on Confluence and then add the documentation. Not without mentioning that it is a very time-consuming and manual process especially when you need to update all these images. It might be possible, however, to get around these constraints by creating a dedicated page for each component in your Figma file so that it displays correctly in Confluence documentation. While it’s a workaround, it can make your Figma file very large and difficult to maintain over time.
The best way to simplify this process is to use a design system-oriented solution like zeroheight that includes features like design upload that eliminate the need for all of this image export and upload.
Another way to display your components is by using add-ons that you can find on Atlassian Marketplace to optimize your design integrations. There are ones for Figma, Sketch, or Adobe XD that allow you to embed specific frames in your documentation. However, relying on too many third-party resources may be risky to maintain your documentation as you depend on their updates. Moreover, most of these add-ons aren’t free (monthly subscription) and can quickly become a high cost for your design system in the long run.
Development integrations
Confluence has very few native features to help you with dev integrations. You can use their code block macro to display code examples with syntax highlighting for various languages (e.g., HTML, CSS, Javascript, PHP, etc.). But if you need to integrate with more design system-oriented solutions, you’ll need to rely on external add-ons from Atlassian Marketplace. You can find dedicated apps for GitHub, GitLab, or Storybook to help you display some live components and source code. But similar to design integrations, beware of relying on external add-ons and plugins because of the maintenance and the cost it might create.
Other integrations
Even if design and development integrations are important for design system documentation, having other types of integrations is always a nice bonus. With their Atlassian Marketplace, Confluence presents a large offering of integration possibilities: security, deployment, project management, tasks, etc. By enabling content embedding from external sources, such as Google Drive, YouTube, and more, this marketplace facilitates the inclusion of elements that enrich the documentation with dynamic visuals, enhancing the user experience. These integrations foster a cohesive and streamlined documentation experience, allowing teams to create, share, and maintain knowledge effectively, ultimately improving collaboration and productivity across projects and teams.
However, as we mentioned multiple times, while Confluence’s integrations enhance its documentation capabilities, heavy reliance on external add-ons and plugins carries inherent risks. The need for maintenance and updates could disrupt the stability of the documentation environment over time. Therefore, a cautious approach to integrating third-party resources is crucial for sustaining a robust and reliable documentation workflow.
Wrap-up
While Confluence is a powerful and comprehensive documentation solution, it might not be well suited to the specific needs of design system documentation. As a centralized platform with integrations within Atlassian’s ecosystem, Confluence offers a cohesive space for collaboration, project management, and documentation. The integration with their ecosystem tools like Jira provides a seamless connection between design system documentation and project tasks, enhancing alignment and productivity. However, while Confluence excels as a general documentation platform, its complexity and lack of design system-oriented features could hinder its effectiveness in this context. Integrating design and dev tools may not be as consistent and powerful as required for design system teams. For instance, integrations with design tools offer embedding options but they lack the automation necessary for comprehensive component integration and maintenance efficiency. Two additional areas where it falls short are the complexity of Confluence’s capabilities which might overwhelm teams as well as its limited customization options, which constrain documentation layout and design. Furthermore, Confluence’s integration capabilities often require reliance on external add-ons, potentially leading to extra costs and complexities in maintaining the documentation setup. Teams must carefully evaluate their requirements and weigh the benefits of centralization and integrations against the potential challenges of complexity, customization limitations, and reliance on external resources. Consider specialized tools designed explicitly for design system documentation, like zeroheight, which could offer a more tailored and effective solution for creating and maintaining a cohesive and user-friendly design system documentation environment. We’re eager to hear from those who have tried building their documentation on Confluence and invite them to share their experiences with us on Twitter (X?) and our zheroes Slack community.