How can Atlassian get better at communicating with developers?

General
1

@remie,

In Introducing the new Developer ID to Marketplace - #8 by remie , you explain the history, as you see it, of Atlassian’s developer comms and why it is currently a problem. I’m going to set aside some of the controversial and confrontational claims. I read that as frustration and confusion. And not just yours but across the developer community. While understanding those sentiments, I can read a core criticism that is well worth discussing:

I acknowledge that we do have cases where comms aren’t consistently published to the Developer changelog, which is the Atlassian standard for developer comms of this sort. This case was not one of those.

Is it unclear that changelog should be the “source of truth” for changes? Do you want Atlassian to focus more on enforcing the changelog as the single “where to post”? Or is there some other problem with changelogs?

Of course, the “where” is separate from “vital information” that partners might miss. Here again, I don’t fully understand how this example prompts the critique. Not only was there a changelog item, but it directly links to this thread so that you can ask questions and get more answers. Atlassians are just people so we don’t always get communication perfect in 1 pass. Hence, the need for multiple channels (changelog as authority, and CDAC as Q&A) to fill the gaps.

Was it a matter of timing? (By the time I looked, both were available, but the CDAC post must have come first so the changelog could have a link.) Broadly, what do you suggest we do? What guidance would you provide to changelog entry authors so they can get more vital information into the first draft? Before getting wrapped up in the accountability of quality, could you help us better understand “what does good enough look like”?

Fundamentally, I acknowledge that we can and should be better at comms. But I disagree that the problem is that comms is “stuck in limbo” or that the solution is as simple as “if only there were a central owner”. I’m here, I’m listening, and I can get improvements made to the tools and practices. What improvement should we make next?

4 Likes
2

Ok, given that it is 11.30pm and I should really just go to bed let me start by saying that I will give more detailed feedback tomorrow. More specifically, because this also involves looking up a lot of old threads. Because we’ve had this discussion before, right here on CDAC.

The problem starts with the fact that no, the change log isn’t the source of truth. The change log is mostly after the fact (the change already occurred), only has little room for details and is scattered all over the place (every product has their own change log). Not all of them are easy to find and sometimes there are changes that impact multiple products that aren’t shared everywhere.

Apart from the change log, we also have CAC, CDAC, Partner portal. There are a lot of changes that impact marketplace partners that are actually posted on CAC.

Then there is the partner portal, which ranges from solution partner / marketing content to technical content. Finding something there is almost impossible, especially because Atlassian often makes pages private for drafts and then changes permissions once it is ready, forgetting the crucial fact that Confluence does not sent “new”/“update” notifications.

Then there is this weird state that many long-running product changes have, where content is both in CDAC, DAC, change logs and Jira tickets (see Platform 7).

Oh and there is of course CDAC.

The problem is that there is no single source of truth. No curated list. No place where marketplace partners can go to get all things Atlassian.

I strongly disagree with this sentiment, because Atlassian was actually really good at this. But it requires a lot of time and effort. It means that product managers understand that changes to the product will impact marketplace partners (meaning that they should not just post on CAC), which used to be the case but has been slipping. And to some extend, for better or for worse, when everyone at Atlassian knew “post on CDAC” was the way to communicate, at least really did have a single source of truth. And Atlassian’s didn’t have to wonder where to post what.

And again, I will look up the receipts tomorrow, but this has been told over and over and over again. That the danger of the decentralised strategy was that Atlassian would no longer understand where to put what herself and that with the lack of a centralised curated overview and dedicated internal education about how and when to involve partners crucial information would get lost in the void.

At some point, we got a half-hearted promise that Atlassian would look into building some sort of tool for a centralised overview, but that never happened. So now we’re stuck to the point in which partners have an unofficial Slack workspace in which we have a community effort to post relevant changes from all different sources to keep each other in the loop. But even then, we still miss out.

So yeah, from a partner perspective, the comms strategy is a mess. Decentralisation can be a good thing (use the right channel for each different type of comms), but it only works if Atlassian makes sure that her comms reaches the intended audience.

7 Likes
3

There are also the RFCs, some of them which are just effectively release notes. The format seems convoluted to start a discussion, but it was a good idea at the beginning.

The Partner Portal is a problem. The actual news (or processes) are diluted in thousands of pages. I’d be curious what the analytics say about the contents. Sometimes writing more doesn’t help. We have difficulty finding the process for each usecase, and my employees never go there for advice anymore, which is sad because there’s a lot of knowledge.

Before that, we had clear advice on the documentation website (I remember when the Marketplace launched, or when Data Center launched, it was just a few pages and the advice was high-density information) and we had CDAC for all news. There is also a big, big, big problem that Atlassian dropped the treeview on the documentation websites, which makes it impossible to browse sibling pages, let alone discover the hierarchy of content.

The Platform 7 communication will be studied for years: Probably 600 questions/bugs from vendors were answered on 25 different CDAC posts, but mainly as comments because every vendor knows posting a new question on CDAC will yield no answer from Atlassian. Huge work from Atlassian to answer all that, and yet, the information is scattered and unbrowseable for the rest of humanity because Atlassian’s developers don’t answer top-level questions on CDAC, and didn’t create a “platform7” category. What should really happen is a dictionary of all bugs we might face when making compatibility with C8.9 and C9.0, all sorted as questions, with one ticked answer like on StackOverflow.

I see huge effort from a lot of Atlassian people in writing and communicating, sometimes with mistakes like posting an RFC when the project is already done and closed, but it’s true that “non-documentation” is the feeling that my dozen developer/marketing employees have, while I know that the information is somewhere out there.

Just for info:

  • We synchronize some changelogs in our Slack, but for example we can’t know when Confluence 8.9 is published,
  • But Remie always seems to find more news when he posts them on the vendors’ Slack,
  • We don’t have CDAC feeds in our Slack, so one again information is scattered.

Thank you team!

5 Likes
4

By the way it’s not too late for Atlassian to copy the 200 unbrowseable comments from the Platform 7’s January post into separate questions, and answer them individually.

3 Likes
5

We are currently in a less-than-ideal situation because the software being used is not well-suited for our communication and documentation needs.

For instance, you are using Discourse for documentation, which is not ideal. Meanwhile, the Developer Docs cannot be commented on, limiting interaction. The Partner Portal on the other hand, which uses plain Confluence with a convenient tree view, makes it easier to find information and allows for threaded discussions. However, it is not being used for technical docs, which is unfortunate.

6

I agree with @remie on this.

Take the release of a new version of Jira, I used to get notified by Atlassian on the date of release through a release notes watch, but for the last couple of years its been customers that ask for updated to the app to support there Jira version. I just haven’t found a source yet that will notify me without me having to go out and check every day.

When I look at Jira Software release notes | Atlassian Support | Atlassian Documentation I’m greeted by this message:

Screenshot 2024-06-07 at 10.08.55
Screenshot 2024-06-07 at 10.08.55778×230 35.7 KB

However, when I look at the Developer Changelog, where the information should be listed, I don’t see any notification related to the actual release, only EAPs

Screenshot 2024-06-07 at 10.10.19
Screenshot 2024-06-07 at 10.10.19956×695 158 KB

If the Developer Changelog is truly THE please to be, single source of truth for changes (and to me that includes actual release announcements) then why isn’t the last changelog for Jira 9.16 the actual release notes? Even if it is just a link.

I really like the Developer Changelog, because I subscribe to specific changes that impact me in Slack, getting a nice notification that may require me to do stuff. It would be great if this really be the single source of truth its claimed to be, now it isn’t.

2 Likes
7

One example of this is the Forge Bitbucket forum. I was surprised when the announcement in the changelog linked to a new category in CAC instead of CDAC. Using CDAC for Bitbucket Cloud and CAC for Forge-specific Bitbucket questions makes it needlessly complicated to find the right information. I think a new CDAC category would have been the better option.

I personally find the combination of changelog and CDAC to be the most practical. I get notifications about new changelogs through the RSS feeds and if a change is relevant for me, I read the linked CDAC post and/or documentation page. This has worked pretty well so far for Cloud/Forge-related changes, but only when the scope was relatively small. When follow-up questions and discussions about major changes (e.g., the deprecation of Confluence REST v1 APIs) are scattered across several CDAC posts, it’s really difficult to keep track of them. And, as @aragot said, new posts are sometimes missed by Atlassian staff as well and remain unanswered.

2 Likes
8

Thank you for posting this topic @ibuchanan. First of all, I second the points highlighted by @remie and @aragot. It’s dizzying to navigate between changelog, CAC, CDAC and the partner portal when there is no apparent policy for what will appear where.

Here are some of my thoughts.
The platform 7 communication has been very hard to follow with a number of CDAC threads, even some changelog entries. Some threads have apparently died, and overlapping threads makes it really hard to follow where updated information will come. A platform 7 topic on CDAC with more high-level posts and less comments on scattered threads would probably be an improvement.

I also feel that the communication would benefit from more openness on estimated date schedules, and coordination between the different teams. Continuing on the Platform 7 topic, it was very confusing for us that the different Data Center teams had such different communication strategies. The Confluence team has had an ongoing communication in a thread with incremental EAP releases. Jira was early communicating, but haven’t implemented platform 7, but it still felt good to have a thread and somewhere we could start asking questions. Meanwhile the Bitbucket and Bamboo teams didn’t make any sound. We could only assume that they were ages from being ready since no communications had been made yet. When they finally added CDAC posts, they have come with extremely short timelines for compatibility testing. They gave the impression of being oblivious to the amount of effort that’s required of the Marketplace partners for compatibility work. I would have loved to get more consistent timeline communications.

A note on the RFC program. No RFC came for Two-Step verification for Data Center: Two-step verification login for Data Center - #25 by MateuszMiodek. It would have been natural to get an RFC of the concept before the EAP announcement, and our feedback and concerns would have been implemented into the first EAP. However, the team has been open to changes and quite transparent in their EAP communications, so kudos to them for that!

9

Ok, so here is my more detailled feedback.

I’ll start by saying that ultimately, this discussion should not be about tooling. The problem space is much broader, and although it is tempting to distract the discussion from something as abstract as comms strategy to something a lot more tangible like tooling, the issue is hardly ever the tool.

In the end, partner communication has a clear goal: convey information about Atlassian to partners. However, achieving that goal is really difficult when dealing with so many moving parts. Because there is a lot of information to convey:

  • Change logs for Jira, Confluence, Bitbucket and Bamboo for both Cloud and Data Center
  • Change logs for Marketplace, Forge, Connect (incl. ACE & ACSB), security, DC approval
  • Marketplace Program, marketing & legal announcements
  • RfCs, EAPs and product announcements (some under NDA) for Jira, Confluence, Bitbucket, Bamboo, Forge, Marketplace, security and Design System
  • Incidents for Jira, Confluence, Bamboo, Bitbucket for both Cloud and Data Center
  • Product documentation for Jira, Confluence, Bamboo, Bitbucket for both Cloud and Data Center, as well as documentation for Forge and Connect (incl. ACE & ACSB)

That’s more than 60 different categories (when counted per product) and I’m probably missing some. And for each category, the comms are often owned by different teams and often these teams do not have dedicated resources for comms.

Each of these categories have different requirements: for instance, a rolling change log makes sense for Cloud as changes can be released continuously, whilst Data Center products have strict versioned releases, for which release notes make more sense. Some categories require discussion and partner input, whereas others are more static. Some information should be persisted for future reference while other information is more fleeting.

I think one of the more problematic assumptions of Atlassian has always been that partners should only subscribe to the channels that they are interested in: why would a Forge developer need to know about Connect? Or a Jira Data Center app about Confluence?

The problem with this assumption is that it lacks two things: cross-product thinking on Atlassian’ part and a fundamental understanding of the marketplace partner community within Atlassian.

Atlassian has become less good in understanding that a change in product X will almost always have impact for partners in product Y. There are a lot of apps that integrate Jira and Confluence, and a change in the way Jira works can have serious impact on those apps in Confluence. Partners will almost always need to understand both Jira and Confluence.

In addition, a lot of partners have optimised their code for both Cloud & Data Center. Changes to Cloud that are not consistently ported to Data Center will impact partners.

I’ve said it before, but Atlassian understanding of what it means to be a marketplace partner is very limited. This is also why some information never reaches Marketplace Partner communication channels, but is only shared on the end-user community forum (CAC) or even LinkedIn.

So instead of having a discussion about which tool is best for which type of communications, the real question is: how do we solve the problem of making sure that the information Atlassian wants to share actually reaches the target audience?

Because I think that is were most of the problems come from, and that is what I eluded to when I mentioned that the change in comms strategy got stopped in track: the change in tooling was implemented, but the communication strategy itself (who get’s access to what, when and where) was not fully rolled out and enforced within Atlassian.

I know that I promised to bring the receipts, and I’m still open to doing that if there is a need for more concrete examples, but having slept on this over night I think we should really focus this discussion on the more abstract level:

How can we make sure that ~60 different categories of comms are streamlined within Atlassian and reach the intended target audience?

5 Likes
10

I second this by Remie! The information space and number of categories is vast. The challenge that must be tackled comprises of understand how the audience and community works, and avoid siloed thinking.

Here I believe it’s important to avoid making incorrect assumptions.
What is important to remember is that the Marketplace partners creating apps are tightly aligned with Atlassian’s products, and integrate to enhance the customer’s experience. Abrupt changes made by Atlassian for her own reasons and motivations are bound to cause problems for partners when we are not made aware in advance. We are a sufficient number of consumers of Atlassian’s APIs and products that Hyrum’s Law applies:

With a sufficient number of users of an API,
it does not matter what you promise in the contract:
all observable behaviors of your system
will be depended on by somebody.

2 Likes
11

There is a still-working set of RSS feeds for app releases, as well as a separate one for EAPs. For example:

Unfortunately, these feeds don’t publish date metadata with each item, which means that the Slack RSS integration doesn’t “see” changes and it cannot be used to ping your workspace. You can still get access them with a RSS reader, but it’s less than ideal.

It would be great if Atlassian could improve these feeds by adding the required metadata so that we can easily consume it.

12

Yeah I remember those, but as you pointed out, no date so no automation at least not the easy kind. If only the date was added to those feeds or the change logged on the changelog, then it would make life so much easier.

13

Thank you all for contributing so far.

I started this thread because it was timely, but it is poorly timed, in the sense that I’m headed out for a week of vacation next week. Please don’t interpret my lack of replies as disinterest, I will study your responses when I’m back at my desk. I’ll drop a few points in response so far before I pause. Hopefully, that will help nudge responses toward what I need to make improvements.

First, I would like to point out how many of you appealed to “partner needs”. While those needs are indeed critical, many of the problems you indicate are made even more difficult to solve when we must communicate to “all developers”. For example, the suggestion that Confluence would be a better solution falls down when we need to onboard every developer. The fact that we do have different audiences to manage will always create some fan-out of the solutions. Here, I would encourage the community to understand @remie ’s point about “this discussion should not be about tooling”. If you want specific features of changelogs, just drop suggestions into JAC/ECO tickets.

Second, the “fan out” that @remie describes is only going to get worse. There are only going to be more “extensibility surfaces” over time. As such, we are going to prioritize. As pointed out, changelog is a better fit for Cloud than Data Center. That’s an explicit prioritization decision. We are trying to build systems (both human and technical services) that can work across the entire ecosystem, but may have better or worse fit depending on the broader ecosystem priorities. Here, I would ask that you focus on not letting perfect be the enemy of good. That’s not an argument that things are good enough now; I’m just setting expectations that I won’t be working on improvements based on problems specific to Data Center.

Third, I’m worried about aggregating the symptoms described here into 1 big problem of “Atlassian comms are broken”. While that’s the kind of appeal that tends to catch attention of my management chain, it fails to recognize quick, practical improvements that we could make to solve problems now. To that point, I accept another of @remie arguments that we need to make sure information is reaching the audience.

I’ll crudely propose a solution (not tooling) that might improve how feedback on comms is perceived, processed, and prioritized by Atlassian (this first thought is not the RFC).
In an appeal to DORA metrics, I’ve been thinking about capturing “change failure”. While some change failures do result in incidents, I think the kinds of problems described here often don’t. So, we need a new signal to understand the impact and then to “multiplex” back to the originating teams. For example, signaling a “removed” API as “announcement” might be a change failure. Or an RFC that is merely release notes. Or, generally, any unanticipated problem that resulted from Atlassian making a change. There will be a need for tooling, but the overall point is that Atlassian current lacks the negative signal when comms aren’t reaching all of you.

Even if you don’t agree with my points above, my ask is to try to think in constructive, targeted terms. I don’t want to be the cause of the next “in limbo promise”. I want real iterative and incremental changes that I can make in the next quarter, or year. That said, upon my return, I’ll do my best to interpret the feedback so far, and any that comes in over the next week for some solutions I can influence.

4 Likes
14

With the v2 Confluence API shitstorm the official statement from Atlassian at some point was (paraphrasing): “we’re not monitoring the forums or engaging any further, submit tickets instead”.

This was after years of aggressively-escalating forum threads being ignored. Occasionally a staff comment would pop into these threads with promises and then they’d ghost it despite repeated follow-up @ mentions.

Then there were partners complaining that when they did submit parity issue tickets, they were being triaged and ignored. Those complaints were also ignored.

I think for these major issues that spiral out of control (v2 API, platform 7, RFCs, Jira navigation etc) the simplest response would be to start running weekly town halls between internal decision makers and marketplace partners.

1 Like
15

Enjoy your vacation @ibuchanan! :beach_umbrella: :cocktail:

1 Like
16

It’s not like Atlassian can’t get it right. Best positive example for me is the DC approval documentation, how-tos and dedicated slack space with a @disturbed engineer on duty. DC app approval is pivotal for Atlassian, vendors and customer success and the right strategies were chosen and investments were made.

IMO Platform 7 and Rest v2 have a similar impact on vendors and eventually customers. In contrast to DC approval the documentation and support provided by Atlassian is scattered, disjointed, unbrowseable and all the rest already mentioned above. Questions are not answered, problems not addressed. I’m deliberately not saying ‘ignored’ because on a fundamental level the feedback loop between ATL and vendors is terribly broken in this process.

  • Do I really need to dig into nested projects in BBC repos to find some specific info and guidance?
  • Why does the absolute minimal plugin skeleton (atlas-create-xyz-plugin) not install and run on Platform 7 products? Has any Atlassian platform 7 decision maker bothered to make sure there is a baseline HelloWorld P7 app created from scratch available and tested for each product?

Nothing or nobody is perfect from day one, but vendors shouldn’t be left feeling alone or behind, right? I can’t quite remember where and when I heard this: “Impossible Alone! -We’re at our best when we work as a team.”
Here is to great teamwork!

2 Likes
17

Thanks for your patience while I was on vacation. The thread seems to have settled down so it feels natural to conclude with my analysis.

The “meta problem” is treating “developer comms” as a single, well-understood problem when it is a “problem complex”. In other words, there are multiple problems, even if closely related. Each needs its own measurement, prioritization, and solution. When we have oversimplified as 1 problem, we have tangled ourselves into projects that are too big to finish in a timely fashion or that miss the mark.

Problems

To help unpack the problem statements, I pointed AI at the thread so far. With some slight adjustments and my own sub-bullets to elaborate with my personal understanding of the problems. While the following problems are not necessarily occurring for every communication, these are so common that we can observe them repeatedly and frequently:

  • Information scattered across multiple channels and platforms.
    • This problem is often expressed as the lack of a solution: a single source of truth for communication. Despite our intent, changelog is not sufficiently authoritative.
    • Even when changelog entries exist, the information developers need might be found in multiple unlinked sources like DAC, CDAC, or Partner Portal.
  • Difficulty in finding relevant information for Marketplace partners
    • With Partner portal (and a set of related, Marketplace-focused channels) Marketplace partners have more channels to worry about, not less.
  • Inconsistencies in communication strategies and channels
    • Across different Atlassian teams, the information is provided through different channels and with varying levels of efficacy. Reality is so different from our model, that our developer community don’t realize we have a standard way.
  • Challenges in understanding the impact of changes across different products
    • Starting from the often obvious problem that we (Atlassian) don’t understand enough about the impact of the changes we’re making.
  • Lack of coordination and openness in estimated date schedules
    • Starting from the often obvious problem that we (Atlassian) don’t have a clear sequence of events and schedule for those events.
  • Issues with communication around major changes like Platform 7 and Confluence’s v2 REST API
    • Major changes often defy our internal model about how changes should happen. Esp for Platform 7 which “introduces” the new concept of “The DC Platform” which used to be implicitly handled in DC product-specific comms. We don’t have good ways to represent that concept across changelogs, DAC, CDAC, etc.
  • Broken feedback loop between Atlassian and marketplace partners
    • On the surface, we (Atlassian) simply don’t listen. RFC comments say, “this is a problem.” We go ahead anyway without addressing the problems. And feedback provided on anything past RFC is often unrecognized.
    • Slightly deeper, when developers (including partners) raise feedback about our comms, there’s nowhere for that feedback to land. The feedback “comms is a problem” is old, giving the impression that nobody at Atlassian is listening.
  • Need for better documentation and support for vendors
    • Even if CDAC is intended to be a Q&A channel about “how to”, it often ends up revealing missing specifications (ie reference docs). This amplifies the feeling of scattered docs & inconsistent comms strategy.
    • Support cases similarly reveal unwritten specs, but without the benefit of making the new information public.
  • Feeling of being left alone or behind in the communication process
    • The changelog is “point in time”, but the “supplemental” information in other channels grows with time. The changelog fails to bring developers along on this journey.

Solution areas

Here are some of the specific solution areas and the rough order of priorities we could work on to relieve the pain:

  • Change failure: introduce the “failure” concept to amplify feedback. First as simple observations, then with consequences.
  • Changelogs: strengthen as “single source of truth for communication”. Consider how to link through to more dynamic sources and better reflect growing understanding over time.
  • Reference documentation: focus on getting “revealed specs” into the authoritative reference docs. Increase discipline about communicating changes to reference docs in the changelog (ie “fixed” and “announced”).
  • Atlassian self-service: improve guidance & tooling. Drive down variation and improve outcomes.
  • API lifecycle: drive consistency with the overall flow. Publicly document the expected lifecycle because it’s not obvious through our actions. Enable the developer community to “call us out” when we fail to adhere to our standard (see change failure).
  • Information architecture (IA): reconcile IA of changelogs, DAC, CDAC, Partner portal, etc. Need to be able to better represent cross-cutting concerns like DC Platform 7.
  • Impact assessment: integrate comms needs into the impact assessment process & tooling.
  • RFC: improve guidance & tooling. Less perfunctory, more outcome oriented.
  • Partner portal: clarify the role of partner comms and the relationship to “all dev comms” (changelogs, CDAC, DAC, etc)

My team will continue to own these items. To continue this conversation into these details, we’ll plan to publish RFCs on each of the above (maybe skipping some like “Atlassian self-service” which are internal facing) where we’ll elaborate solutions.

4 Likes