TL;DR
The Atlassian Editor team is rolling out a number of sizeable changes to the way macros exist in Confluence Cloud. We’re shipping a new:
- Configuration experience to help users stay in context when editing macros
- Element Browser to help users find both native elements and macros (in a prettier way, too)
- Top toolbar + dropdown to help users insert elements into the editor in a more consistent way
We need you to:
- Read this blog and understand the impact to you. We’ll be following up in the next ~1 month with another blog with concrete asks for you to dogfood the experience with your app. Note, dogfooding will only be available for partners in the Confluence Cloud: Developer-First Rollouts for Ecosystem App Developers Group".
- Complete this 1 minute survey re; new browser categories to help us understand if our new proposed categories make sense. Please do so by Jan 15, 2021.
- Leave any questions or comments on this blog
Background
Extensibility in the Confluence Cloud Editor is critical for a number of reasons. For:
- Our mutual customers , it’s how they truly unleash the power of products to service their specific needs. Macros provide users the ability to supercharge their Confluence documents with all manner of wonderful experiences and features.
- You as partners , it’s how you create value for our mutual customers, and inherently, how you create a thriving business for yourselves.
- Atlassian , it’s how we scale our ability to deliver value to our mutual customers by having more external teams building on the editor.
For all the value the historical extensibility model in the editor provided, it had a number of downsides. For:
- Our mutual customers , the UX was at times unintuitive, disruptive, and out of date. For example, when editing a macro, the configuration would appear over the macro itself, making it impossible for the user to see what content they were editing without opening a second tab. Our macro browser also didn’t align to our current design guidelines.
- You as partners , could only build macros/apps for a single product, Confluence. There was no opportunity to surface and sell your app in other products’ editors (e.g. Jira’s editor).
What is changing?
With an understanding of the challenges mentioned above, we’ve reimagined and rebuilt our extensibility experience.
A new content discovery experience
We’ve overhauled the old school macro browser, giving it a lick of paint (i.e. aligning it to current design guidelines) and bringing native elements into the browsing experience. We now not only surface existing macros, like the Table of Contents macro, but also surface all other native elements that can be inserted into the editor, like panels and expands. This creates consistency with what is available in our other insert menus such as the slash command. Furthermore, it’ll work in all products, not just Confluence (in the future - more on that later).
Our + menu in the top toolbar dropdown has also been overhauled to look and feel the same as the / command and Element Browser. A search field has been added to the top to enable quick search of macros and native elements.
Before
After
As part of this new browsing experience, we’ve done research to update the categories in the left sidebar of the browser. We had a belief that the categories didn’t map too intuitively to all the apps. We validated this with user testing and have come up with a better performing list of categories. As a final test of these categories before we implement them, we’d love to get your thoughts on what category you think your app would make sense to map to. Can you please fill out this 1 minute survey to help us make this experience as awesome and intuitive as possible - follow this link to Google Forms.
Contextual configuration
To solve the problem of taking users out of context when configuring their macros, we’ve built extension configuration into the new side panel in Confluence. This aims to provide a far greater WYSIWYG experience for users, enabling them to see the extension they’re configuring whilst configuring it.
As partners, you don’t need to do anything for this. We’ve migrated all your configuration experiences to the sidebar. Note: there are a small group of macros that have custom configuration that won’t initially work in the new configuration panel. For these they will continue to use the old configuration. We have a flag that will recognize when custom configuration is used and will automatically fallback to the old configuration experience. Over time, we will work to define a path forward for these macros as well.
A more extensible editor
One of the big advantages of this new approach, beyond the UX, is the fact that configuration and browsing of macros can happen in any Atlassian cloud product that has the new editor. This theoretically means that you can build a macro once, and sell it to a lot more users across Jira, etc. Unfortunately, we won’t be able to ship this in the short-term as products like Jira still have some issue views that use the markdown editor. If a user were to insert an extension in an issue’s new editor, then someone else were to view/edit it in the old editor, we’d corrupt their content. We’re currently looking at ways around this. We’ll let you know when we’re getting close to launch!
Our rollout plans
As this is a sizeable UX change, we’re going to do a conservative rollout. Stages of rollout are outlined below. Exact dates will be announced shortly on Community. We’re just finalising some dev work and testing on our side:
- Rollout new experience internally at Atlassian and on your testing instances through the “Confluence Cloud: Developer-First Rollouts for Ecosystem App Developers Group” for dogfooding. We’ll take feedback and make appropriate fixes over the course of ~4 weeks.
- Start progressive rollout to customers. We’ll incrementally rollout over ~4+ weeks.
During this rollout time, we’ll also be sending out communications to our customers about the upcoming changes.
What do you need to do?
We’ll let you know shortly about dogfooding dates where you’ll be asked to test your app. In the meantime, can you please complete this 1 minute survey re; new browser categories to help us understand if our new proposed categories make sense. Please do so by Jan 15, 2021.
As you’re building new apps in the future, please consider the new UX, ensuring that your configuration makes sense in the new model. If we have any gaps with what we’re providing, please also let us know so we can make things better!
We hope you’re as excited about this as we are!
Jonno Katahanas | Product Manager for the Atlassian Cloud Editor
