4 Principles of App Design

Designing apps for the Atlassian platform presents some unique challenges and limitations. In this article, we share K15t's four principles of app design that we use to build apps that work well for Confluence and Jira users.

Why App Principles Can Help

Developing new features or apps can be challenging and require some tough decisions. App principles help us make these decisions by providing a shared framework for our teams and conveying a philosophy to our users.

That said, app principles should not be seen as absolute rules. In some cases, they may even conflict with one another. By embracing these tensions, you can create a better experience for your users and increase their chances of success.

K15t's 4 App Principles

Over the years, we've developed four app principles that have helped us develop great apps that are well-known in the Atlassian Ecosystem. While you may adapt one or more of these principles, we recommend finding your own principles that your team can identify with.

1. Simple, yet powerful

Our first principle guides us in building apps that are easy to understand and simple to use, while still being powerful. As our users may not know what they want until we show it to them, we want to be opinionated and guide them in using our apps. At the same time, we want to offer extension points and APIs in our apps, so that more sophisticated users, partners, and solution partners can automate, extend, and integrate with our apps.

From powerful to simple – an example

Scroll Viewport for Confluence Server was a very powerful product in its early days. Our users had the full flexibility of HTML/CSS/JS to build their own themes. But with all that power, they didn't have a simple way to start, which led to problems in two ways:

1. New users didn't know how to start, which lead to low adoption.

2. For the users who did push through and use Viewport, many didn't understand HTML/CSS/JS, causing a lot of support effort on our end and some frustration on behalf of the users.

In 2019, we took on this challenge and developed the Help Center theme for Confluence Cloud, which provides customizations for the theme without the need to know HTML, CSS, or JS. These changes were a hit!

Scroll Viewport for Confluence Cloud is very simple product to get started with, as users can get rolling right away using the theme editor. But this also came with a compromise: our users didn't have full flexibility in styling their Scroll Viewport sites. We've since enabled users to add custom CSS and JS to work around this. 

2. Build with Atlassian, not against them

Our second principle is to extend and improve the capabilities of Atlassian Confluence and Jira. In order to better integrate and improve user adoption, we want to extend the existing functionalities and patterns of these tools and not work around familiar concepts or try to bypass them. The same is true when it comes to terminology; we want to stick to known terminology wherever possible.

Example: Scroll Content Management

Building with Atlassian Confluence means enabling Confluence users. These users don't want to learn new paradigms or metaphors. We can't expect them to learn new concepts from our apps, and it's on us to meet them where they are.

To some extent, Scroll Versions and Scroll Documents do require users to learn new concepts:

• Scroll Versions introduced an abstraction layer and several UI tweaks. At some point, users also needed to understand the concept of Scroll Versions, because the abstraction is "leaky" in places where we haven't tweaked the UI. For example, Scroll Versions creates a new page for each version and prefixes those with a dot to hide them in the regular Confluence UI. This means that there are some cases (like when searching) where these pages become visible to the user.

• Scroll Documents, on the other hand, is different because it doesn't tweak the UI as much, but it adds additional custom UIs like viewing the created document in a reader. This means that users need to learn the new concept of a "document," which results in a steeper learning curve and requires more explanation – something we are aware of and try to improve where we can.

In software development, there is the law of Leaky Abstractions, which can be also applied here:

All non-trivial abstractions, to some degree, are leaky.

3. Focus on teams first

In our third principle, we agree that the common denominator in companies of all sizes is teams – no matter the head count. Enterprises consist of dozens or hundreds of teams, while startups may only have one. With our apps at K15t, we want to focus on the teams and make their lives easier instead of focusing on specialized features that only work for single users or in an enterprise context. This principle helps us focus on what matters most to making these teams successful.

Tip: Be aware of feature requests from personas which aren’t your target users

Many of our customers at K15t ask for advanced functionality that is required in large organizations, like detailed permission settings for apps.

These requests often come from the Aziza persona, who wants to lock down functionality in order to keep the tools simple and fast – which from her perspective, apps tend to sabotage.

Focusing on teams means that we react to these kinds of requests with care because in most cases, the requested functionality doesn't increase (and often hinders) value for our end-users (Maggie and Conrad). On the other hand, we have to take into consideration that some of this functionality might be a blocker for large customers.

As a part of this principle, also consider which stage a product is in. The more mature it gets, the more it makes sense to add advanced functionality. For newer products, value creation for teams should be your priority.

4. Apps build solutions

The fourth and last app principle at K15t is that our customers often start by using just one of our apps, but might end up with the whole portfolio. In that sense, an integrated use case should always be top-of-mind. Our apps need to work on their own, but should also unleash their full potential in combination with the whole portfolio.

How this principle influenced the Scroll Apps for Confluence

A few years ago, our apps Scroll Viewport, Scroll Documents, and the Scroll Exporters had seen success as standalone apps. However they didn't work well together (particularly on Confluence Cloud) and there wasn't any additional value in owning all of them as a team.

Our principles helped us focus on this issue, and we have since dedicated several initiatives within the company to better integrate all of our apps. Today, with Scroll Documents, you can version or translate your documentation and export or publish these documents with Scroll Viewport or the Scroll Exporters. This creates a comprehensive solution for our users and enables them to manage and present their content in various ways.

Conclusion

As you can see from the examples, K15t's app principles helped us build a successful portfolio of apps for the Atlassian Marketplace and helped us deliver as much value as possible for our customers. What's more, they help new team members get an idea of what matters most when developing apps at the company.

App principles are a powerful guide for app and feature development across the company, but keep in mind that they shouldn’t be seen as fixed rules that can't be bent.