UPDATE AS OF 21 APRIL: Initial slated rollout starting on April 19 has been pushed back a couple of weeks to deploy a few final changes. We’re now aiming to start rollout on ~10 May.
TL;DR
As previously announced in December 2020, 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
- Browser to help users find both native features/content types and macros (in a prettier way, too)
- Top toolbar + dropdown to help users insert features/content types into the editor in a more consistent way
We need you to:
- Read this blog and understand the impact to you.
- Dogfood your apps and provide feedback through this blog (i.e. add a comment), directly to jkatahanas@atlassian.com, or set up a meeting with me. Note, dogfooding will only be available for partners who have signed up to be part of the dogfooding group for this feature; this already includes all instances signed up to the Confluence Cloud: Developer-First Rollouts for Ecosystem App Developers Group. Please complete dogfooding by Mar 12, 2021.
- If you haven’t already, complete this 1 minute survey re; new browser categories to help us understand if our new proposed categories make sense. Please do so by Feb 26, 2021.
- Update any of your marketing material, app store listings, etc, with any changes that your app will have from a UX POV. This is up to you when you do this, if at all. Our recommendation is to do so as soon as possible.
- Leave any questions or comments on this blog
Note: As with any rollout of a big new change, unplanned things can arise. This timeline is our best guess with current information at hand. It’s subject to change if we encounter any issues we weren’t expecting.
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 features/content types into the browsing experience. We now not only surface existing macros, like the Table of Contents macro, but also surface all other native features/content types 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 Browser. A search field has been added to the top to enable quick search of macros and native features/content types.
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 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: Some macros that have custom configuration 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. Please let us know if this is you and what your requirements are.
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 the dev 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 dogfooding group for dogfooding. We’ll take feedback and make appropriate fixes over the course of ~4 weeks. We’ve recently started internal dogfooding at Atlassian. Partner dogfooding will run from the date this blog is published (Feb 11, 2021) and go until ~Mar 11, 2021.
- Finalise any remaining changes we need to make pre-rollout and go through our internal rollout process. This will finish on ~Apr 2, 2021.
- Start progressive rollout to customers on ~May 10, 2021. We’ll incrementally rollout over ~4+ weeks. We will start rollout to 10% of customers. Every week after (assuming no issues occur), we will progressively rollout to 25%, 50%, then 100% of non-enterprise customers. From ~June 7, 2021 we will rollout to the remaining enterprise customers.
During this rollout time, we’ll also be sending out communications to our customers about the upcoming changes.
Note: As with any rollout of a big new change, unplanned things can arise. This timeline is our best guess with current information at hand. It’s subject to change if we encounter any issues we weren’t expecting.
What do you need to do?
#1 Dogfood and give feedback: Please dogfood and give us feedback! When we rollout to the partner dogfooding instance, please spend time testing your app and giving us feedback.
If you find bugs, please let us know:
- Current behaviour
- Expected behaviour
- What you were doing when it occurred
- What browser you were using
- How to reproduce, if possible
If you have suggestions, please let us know:
- Current behaviour (or what doesn’t exist)
- What you want to exist
- Why / user problem it solves / use case
When giving feedback, the more information you can provide, the better.
#2 Complete survey re; browser categories for your apps: 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 Feb 26, 2021.
#3 Design and build future apps with the new experience in mind: 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!
If you have the question - “How do I build new apps using this new config?” There’s a simple answer:
- If you’re building a Forge app, this is the only configuration that is possible to use. You don’t need to do anything new. Just follow the Forge docs.
- If you’re building a Connect app, you’ll need to follow these docs.
Some other things to note about the current experience in dogfooding
We’ve already been dogfooding this for about a week internally and have found a number of bugs and UX issues. There is a team working through them to get them fixed before going to customers. If you find any issues with your macros, check this list of known issues and see if it’s related.
Thanks for all your input on this new experience. We hope you’re as excited about this as we are!
Jonno Katahanas | Product Manager for the Atlassian Cloud Editor
